在实作 Web 服务时,会需要去读取客户端发送来的 HTTP 请求标头中的 User-Agent 字段,来判断客户端是使用什么产品(如应用程序)和 Web 引擎来发送请求,以及客户端环境的操作系统、CPU 架构和所用的设备等信息。

Linux Mint 上 Firefox 60 ESR 所发送的 HTTP 请求中的 User-Agent 字段内容如下:

Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0

从以上内容,我们可以知道这个客户端的操作系统是 Ubuntu,浏览器是 Firefox,Web 引擎是 Gecko,CPU 架构是 x86_64 (amd64)。我们只要用一个正则表达式,就可以很轻易地用程序抓出这些信息。

不过,事实上,User-Agent 字段的内容几乎没有格式的限制,例如 Apple Watch 发送出来的 User-Agent 字段内容如下:

atc/1.0 watchOS/5.1.3 model/Watch3,4 hwp/t8004 build/16S535 (6; dt:156)

所以要对 User-Agent 字段的内容进行完美解析是不可能的事情。还好,在 GitHub 上有一个 uap-core 开源项目,整理了用来解析已知(有流通)的 User-Agent 的正则表达式(都存在 regexes.yaml 文件中),以及在各种场景下的测试案例。

然而,uap-core 只有整理解析 User-Agent 中产品、操作系统和设备的部份,而并没有 CPU 架构和 Web 引擎。后面这两个未支持的部份,在 ua-parser-js 这个开源项目是有支持的,而且也是使用正则表达式来解析。

也就是说,我们其实可以利用 uap-core 和 ua-parser-js 提供的正则表达式,来在 Rust 编程语言中实现解析 User-Agent 字段的功能。

User Agent Parser

「User Agent Parser」是笔者开发的套件,受到 uap-core 和 ua-parser-js 的启发,可以用来解析 User-Agent 字段,从中获得客户端的产品、操作系统、设备、CPU 架构和 Web 引擎等信息。

Crates.io

Cargo.toml

user-agent-parser = "*"

使用方法

创建 regexes.yaml

以下是一个简单的 regexes.yaml 范例:

user_agent_parsers:
  - regex: '(ESPN)[%20| ]+Radio/(\d+)\.(\d+)\.(\d+) CFNetwork'
  - regex: '(Namoroka|Shiretoko|Minefield)/(\d+)\.(\d+)\.(\d+(?:pre|))'
    family_replacement: 'Firefox ($1)'
  - regex: '(Android) Eclair'
    v1_replacement: '2'
    v2_replacement: '1'

os_parsers:
  - regex: 'Win(?:dows)? ?(95|98|3.1|NT|ME|2000|XP|Vista|7|CE)'
    os_replacement: 'Windows'
    os_v1_replacement: '$1'

device_parsers:
  - regex: '\bSmartWatch *\( *([^;]+) *; *([^;]+) *;'
    device_replacement: '$1 $2'
    brand_replacement: '$1'
    model_replacement: '$2'

regexes.yaml 为一个 Map 结构,user_agent_parsers 这个键值存放着解析产品所需的正则表达式和取代字符串的样本,os_parsers 这个键值存放着解析操作系统所需的正则表达式和取代字符串的样本,device_parsers 这个键值存放着解析设备所需的正则表达式和取代字符串的样本。取代字符串的样本中,如果有以钱字号 $ 来接着数字的部份,就会被这数字对应到的正则表达式群组所匹配到的字符串来取代。

如果不需要自行撰写 regexes.yaml 的话,可以到 uap-core 项目中取得标准的 regexes.yaml。

读取 regexes.yaml

创建好 regexes.yaml,可以利用 user_agent_parser 这个 crate 所提供的 UserAgentParser 结构体的 from_path 或是 from_str 关联函数来读取,并创建出 UserAgentParser 结构实体。

from_path 可以从文件读取 regexes.yaml 的数据,例如:

use user_agent_parser::UserAgentParser;

let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();

from_str 可以从内存读取 regexes.yaml 的数据,建议搭配 include_str 宏一同使用,例如:

use user_agent_parser::UserAgentParser;

let ua_parser = UserAgentParser::from_str(include_str!("/path/to/regexes.yaml")).unwrap();
解析

利用 UserAgentParser 提供的名称以 parse_ 为开头的方法,来解析透过参数传入的 User-Agent 字段内容的字符串。

例如:

use user_agent_parser::UserAgentParser;

let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();

let user_agent = "Mozilla/5.0 (X11; Linux x86_64; rv:10.0) Gecko/20100101 Firefox/10.0 [FBAN/FBIOS;FBAV/8.0.0.28.18;FBBV/1665515;FBDV/iPhone4,1;FBMD/iPhone;FBSN/iPhone OS;FBSV/7.0.4;FBSS/2; FBCR/Telekom.de;FBID/phone;FBLC/de_DE;FBOP/5]";

let product = ua_parser.parse_product(user_agent);

println!("{:#?}", product);

//    Product {
//        name: Some(
//            "Facebook",
//        ),
//        major: Some(
//            "8",
//        ),
//        minor: Some(
//            "0",
//        ),
//        patch: Some(
//            "0",
//        ),
//    }

let os = ua_parser.parse_os(user_agent);

println!("{:#?}", os);

//    OS {
//        name: Some(
//            "iOS",
//        ),
//        major: None,
//        minor: None,
//        patch: None,
//        patch_minor: None,
//    }

let device = ua_parser.parse_device(user_agent);

println!("{:#?}", device);

//    Device {
//        name: Some(
//            "iPhone",
//        ),
//        brand: Some(
//            "Apple",
//        ),
//        model: Some(
//            "iPhone4,1",
//        ),
//    }

let cpu = ua_parser.parse_cpu(user_agent);

println!("{:#?}", cpu);

//    CPU {
//        architecture: Some(
//            "amd64",
//        ),
//    }

let engine = ua_parser.parse_engine(user_agent);

println!("{:#?}", engine);

//    Engine {
//        name: Some(
//            "Gecko",
//        ),
//        major: Some(
//            "10",
//        ),
//        minor: Some(
//            "0",
//        ),
//        patch: None,
//    }
生命周期

parse_* 方法所回传的数据模型实体,其生命周期相依于 User-Agent 字段内容的字符串和 UserAgentParser 结构实体。如果要让模型没有生命周期相依性,可以使用其提供的 into_owned 方法。

use user_agent_parser::UserAgentParser;

let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();

let product = ua_parser.parse_product("Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.12) Gecko/20101027 Ubuntu/10.04 (lucid) Firefox/3.6.12").into_owned();

Rocket 框架支持

Rocket 是 Rust 的一个 Web 框架(Web Framework),如果想要让 Rocket 能够解析 User-Agent 字段的话,可以考虑与这个 User Agent Parser 一同使用。首先要激活 User Agent Parser 的 rocket 特色,Cargo.toml 设置档的写法如下:

[dependencies.user-agent-parser]
version = "*"
features = ["rocket"]

接着那些 parse_* 方法所回传的数据模型,也就是 Product、OS、Device、CPU、Engine 结构体,就可以直接被当作请求守卫来用了!另外,如果不想解析 User-Agent 字段的内容,也可以使用 UserAgent 这个请求守卫。不过要记得将一个 UserAgentParser 结构实体注册给 Rocket 使用。

程序范例如下:

#[macro_use]
extern crate rocket;

use user_agent_parser::{UserAgentParser, UserAgent, Product, OS, Device, CPU, Engine};

#[get("/")]
fn index(user_agent: UserAgent, product: Product, os: OS, device: Device, cpu: CPU, engine: Engine) -> String {
    format!("{user_agent:#?}\n{product:#?}\n{os:#?}\n{device:#?}\n{cpu:#?}\n{engine:#?}",
            user_agent = user_agent,
            product = product,
            os = os,
            device = device,
            cpu = cpu,
            engine = engine,
    )
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .manage(UserAgentParser::from_path("/path/to/regexes.yaml").unwrap())
        .mount("/", routes![index])
}