那天的工作是给一个小工具加个 HTTP 接口。cargo new rustdemo 之后不到半小时,项目就卡在三处:照两年前的教程把路由写成 /api/items/:id,请求 /api/items/1 返回 404;再开一个终端启动同一个程序,控制台报 os error 10048;把 State 提取器加进处理函数,编译直接失败,错误指向 Router 的 with_state。

这三件事分别对应版本语法、端口占用和状态注入,没有一件是 Rust 语言本身的问题,全部属于「怎么把服务装起来」这一层。本文只讲这一层:从空目录走到能用 curl 访问的 JSON 服务,同时把「为什么选 Axum、和 Actix 差在哪」讲清楚。所有权、trait、泛型那类内容归语言方向,这里遇到只顺带解释一句。

先把范围说死:这篇结束时,你会得到一个监听 127.0.0.1:18080、带一个 /health 接口、连接 SQLite 并返回 JSON 的单文件服务。它不是玩具工程的最终形态,但每个依赖和每行代码都能解释,后面五篇都从这个骨架往上加。

先看现象:起步阶段最容易踩的八个坑

新手在这一步耗掉的时间,通常不是花在写代码上,而是花在「报错看不懂」上。下面这张表按「看到什么、真实原因、先查哪里」排,建议遇到问题时从上往下对一遍,比凭感觉改代码快。

现象真实原因第一步查什么
照教程写 /api/items/:id,请求后 404Axum 0.8 的路径参数改用花括号,冒号写法只属于 0.7看 route 里参数那一截,改成 {id}
编译报 State 相关的 trait bound 不满足用了 State<AppState> 提取器,但 Router 末尾没有 .with_state看路由链最后一行有没有把状态喂进去
启动报 os error 10048Windows 上端口已被占用,10048 就是「地址已被使用」netstat -ano | findstr :18080 找到进程号
改一行代码,cargo run 又要等很久debug 构建加依赖重编,首次和增量是两回事确认是不是改了 Cargo.toml 触发全量依赖重编
路由明明写了,curl 仍 404HTTP 方法不匹配,例如路由是 POST,请求发的是 GET用 curl -i 看清状态码和请求方法
返回 415,body 解析失败请求没有带 Content-Type: application/jsoncurl 加上 -H "Content-Type: application/json"
接口 500,控制台却什么都没有处理函数 panic,且没有装日志与 panic 输出看 stderr 原始输出,先接上 tracing
健康检查里 db 是 falseSQLite URL 少了 mode=rwc,或工作目录里没有库文件看启动日志里的连接结果和当前工作目录

这张表里只有第一条是「版本问题」,其余都是环境或配置。很多教程写于 0.6、0.7 时代,代码片段本身没错,只是版本对不上。遇到诡异的 404,先确认版本,再确认方法,最后才怀疑框架。把版本写进项目说明,是这个阶段最省事的一条纪律。

端口 10048 那条值得单独说。Windows 的错误码和 Linux 不一样,Linux 上是 Address already in use,Windows 上是 10048。上一次 cargo run 的进程没有真正退出,或者另一个项目占了同一个端口,都会出现这个报错。用 netstat 找到 PID 再决定是结束它还是换端口,别反复重启碰运气。

Axum 和 Actix:先讲清楚取舍

Axum 是建立在两个成熟库之上的框架:hyper 负责 HTTP 协议的解析与连接管理,tower 负责「中间件」这种可叠加的服务抽象,异步运行时用 tokio。你可以把 Axum 理解成一层薄薄的粘合层:把 hyper 的请求交给 tower 的服务栈,再用提取器(extractor)把请求各部分拆成函数参数。薄的好处是行为和底层一致,出错时能顺着 hyper 和 tower 的文档查;代价是它不替你做业务层的事,认证、ORM、后台管理都要自己选。

Actix-web 走的是另一条路。它有自己的 worker 模型:每个 worker 一个单线程运行时,处理函数在 worker 的本地任务集里跑,因此不要求 Send。这意味着你可以在处理函数里用 Rc、RefCell 这类单线程结构,写起来更像传统回调式框架。代价是跨 worker 共享状态必须自己保证线程安全,而且生态里的中间件、扩展大多围绕 Actix 自己的抽象,迁移到别的框架并不轻松。

选 Axum 的理由

handler 是普通 async 函数,提取器把 Path、Query、Json、State 拆得干净;tower 生态里的超时、限流、追踪、CORS 可以直接复用;和 tokio、hyper、tonic 的技术栈一致,后面接 gRPC 或自定义协议不用换脑子。要求处理函数可跨线程执行,编译期就会拦住「把锁跨 await 持有」这类隐患。

选 Actix 的理由

单机吞吐长期在压测榜前列,worker 模型对 CPU 密集和大量短连接很友好;处理函数不要求 Send,某些依赖单线程上下文的库接进来更顺;如果你已经有一个跑了三年的 Actix 项目,迁移到 Axum 的收益通常抵不过重写路由、中间件和状态管理的成本。

编译时间是选型时最容易被忽略、又每天都要付的成本。本机 Windows 11、rustc 与 cargo 都是 1.99.0,Axum 工程的首次 cargo build(含全部依赖)用了 2 分 03 秒,之后改代码的增量构建是 50.73 秒。作为对照,同样两个接口的 Actix 对比工程,冷依赖构建用了 2 分 48 秒,actix-web 版本是 4.18.2。差距不到一分钟,但如果你一天要重编十几次,这个差距会变成真实的等待。

需要说明的是,二进制体积、release 构建产物的启动耗时,这两项我没有在本机实测,网上常见的对比数字口径也不一致,本文不给结论。能确认的只有上面两个构建时间和运行时的行为差异。选型时把「编译时间、团队熟悉度、生态复用」三件事摆在一起看,比看一张吞吐排行榜更实际。

反过来也要讲:Axum 不是默认答案。如果你的服务就是几个静态接口、团队里没人写过 tokio,Actix 的文档和示例同样能让你当天上线;如果你的项目只需要一个极简 HTTP 层,甚至可以直接用 hyper,连 Axum 都不必引入。框架是成本,不是身份。

这里的对比只覆盖本机可以验证的部分:构建时间和运行时模型。吞吐、内存占用、二进制体积要同一台机器、同一份压测脚本才可比,本文不做跨项目的数字比较。选型时把这三项换成你自己场景里的权重,比背结论有用。

环境、依赖与目录

本机环境是 Windows 11,rustc --version 和 cargo --version 都是 1.99.0。Axum 用 0.8.9,数据库驱动用 sqlx 0.8.6,异步运行时是 tokio 1.x,序列化用 serde 与 serde_json 1,日志用 tracing 0.1 加 tracing-subscriber 0.3(开 env-filter)。这些版本不是随便写的,路径语法、提取器签名、连接池 API 都会随版本变,照抄前先对齐。

建工程只要一行:

cargo new rustdemo
cd rustdemo
cargo add axum@0.8.9
cargo add tokio@1 --features full
cargo add serde@1 --features derive
cargo add serde_json@1
cargo add sqlx@0.8.6 --features runtime-tokio,sqlite
cargo add tracing@0.1
cargo add tracing-subscriber@0.3 --features env-filter

cargo add 会自动改 Cargo.toml 并解析版本。手写也行,最终文件长这样,注意 edition 用 2021 即可,不必为了「新」去改 2024:

[package]
name = "rustdemo"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.8.9"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

目录先保持最小。后面几篇会往里加文件,但起步阶段不要一次性铺开分层,否则连「哪个文件在跑」都说不清:

Cargo.toml依赖与包信息。改这里会触发依赖重编,日常改代码不会。
src/main.rs唯一入口。路由、状态、监听都先塞在这里,看得见全貌。
app.dbSQLite 库文件。第一次用 mode=rwc 启动时自动创建。

首次构建前先跑一次 cargo build,把依赖全部编译好。实测这一步 2 分 03 秒,期间会下载并编译几十个 crate,机器风扇转起来是正常的。之后再 cargo run,只编译你自己改动的 crate,实测增量 50.73 秒。如果每次 cargo run 都像第一次那么久,先看是不是 Cargo.toml 被改动,或者杀毒软件在扫描 target 目录。

版本要写死到小版本,至少在 Cargo.toml 里锁到次版本。Axum 0.7 到 0.8 改的不只是路径语法,提取器的 trait 边界、serve 的签名也有变化。cargo add 默认给的是兼容范围,团队协作时把 Cargo.lock 提交上去,能避免「昨天还能编,今天拉下来就报错」这种最难查的差异。升级依赖不要和改业务混在同一次提交里,否则编译失败时你分不清是谁引起的。

main.rs:从空文件到监听端口

先解释两个宏和函数的关系。#[tokio::main] 是属性宏,它把你写的 async fn main 包成一个普通 main,在内部创建 tokio 运行时并阻塞等待 future 完成。没有它,async fn main 根本不能作为程序入口。axum::serve(listener, app) 返回一个 future,必须放在运行时里 .await,否则什么都不会发生。两者一个是「提供运行时」,一个是「使用运行时」,缺一不可。

状态注入有两种常见写法。第一种是 Router::with_state(state),把状态类型参数固定在路由上,处理函数用 State<AppState> 取;第二种是自己包一层 Arc<AppState>,处理函数直接取 State<Arc<AppState>>。Axum 的 State 提取器要求状态实现 Clone,而 Arc 的克隆只是引用计数加一,所以对于包含连接池、配置、计数器的共享状态,Arc 是标准做法。本例里的 AppState 只含一个连接池和一个 Instant,两者本身克隆都很便宜,直接 with_state 就够;后面要放可变缓存时,再在外面套 Arc。

完整代码如下。注意 SQLite 的 URL 用了 sqlite://app.db?mode=rwc,mode=rwc 表示文件不存在就创建、存在就可读写;少了它,第一次启动会直接报「unable to open database file」。

use std::time::Instant;

use axum::{extract::State, routing::get, Json, Router};
use serde::Serialize;
use sqlx::sqlite::SqlitePoolOptions;

#[derive(Clone)]
struct AppState {
    pool: sqlx::SqlitePool,
    started: Instant,
}

#[derive(Serialize)]
struct Health {
    status: &'static str,
    db: bool,
    uptime_secs: u64,
}

async fn health(State(state): State<AppState>) -> Json<Health> {
    let db = sqlx::query("SELECT 1")
        .fetch_one(&state.pool)
        .await
        .is_ok();
    Json(Health {
        status: "up",
        db,
        uptime_secs: state.started.elapsed().as_secs(),
    })
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::new("rustdemo=info"))
        .init();

    let pool = SqlitePoolOptions::new()
        .connect("sqlite://app.db?mode=rwc")
        .await
        .expect("open sqlite");

    let state = AppState {
        pool,
        started: Instant::now(),
    };

    let app = Router::new()
        .route("/health", get(health))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:18080")
        .await
        .expect("bind 18080");

    tracing::info!(port = 18080, "listening");
    axum::serve(listener, app).await.expect("server");
}

几个细节值得对照着看。health 的返回值是 Json<Health>,Json 是提取器也是响应类型,当返回值用时它会自动设置 content-type: application/json。State 放在参数最前面,提取器按参数顺序执行,这条规则第 2 篇会展开。Instant::now() 在启动时记录,elapsed().as_secs() 得到运行秒数,所以刚启动时 uptime_secs 是 0。

还有一个容易忽略的点:.with_state(state) 必须放在所有需要状态的 route 之后。Axum 的类型系统会把「还没有状态的路由」和「已经补上状态的路由」区分开,axum::serve 只接受后者。顺序写错时的报错很长,但关键词是 MissingState 或 trait bound 不满足,看到就去检查这一行。

不要在 main 里对端口绑定以外的启动步骤随手 unwrap。数据库没起来时,expect 会让进程直接退出,systemd 或容器会不停重启,日志里只剩一行 panic。要么在启动阶段明确失败并输出可读原因,要么把「数据库暂时不可用」降级成健康检查里的 db:false,让进程先活着,交给运维判断。端口绑定失败则相反,应该立刻退出,因为换端口是人的决定,不是程序的。

跑起来:curl 看到的到底是什么

在工程目录执行 cargo run。tracing 默认输出带 ANSI 颜色码,下面的日志是去掉颜色码之后的可读版本:

INFO rustdemo: listening port=18080

这行日志来自 tracing::info!(port = 18080, "listening"),rustdemo 是事件的目标(默认取 crate 名)。它证明两件事:代码执行到了监听之前,tokio::net::TcpListener::bind 成功了。如果这行没有出现,先看端口错误,而不是看路由。

curl 用下面的形式即可。省略协议前缀时 curl 会按 http 处理,本机端口不需要额外参数:

curl -s -i 127.0.0.1:18080/health

实测返回:

HTTP/1.1 200 OK
content-type: application/json

{"status":"up","db":true,"uptime_secs":0}

状态码 200 说明请求进了处理函数并正常返回。content-type 是 Json 响应自动加的,不用手写头。db 为 true,表示 SELECT 1 在连接池上执行成功;如果这里是 false,问题在数据库文件和连接串,接口层是好的。uptime_secs 为 0,是因为服务刚启动,等十几秒再请求就会变大。别把 0 当成 bug。

注意响应体里没有换行,字段顺序按结构体声明顺序。用浏览器打开也可以,但浏览器会加一堆请求头,排查时用 curl 更容易看清原始返回。如果返回 404,先看路由是不是写成了 /api/health 而请求发的是 /health,这种前缀不一致在起步阶段非常常见。

日志里的颜色码是 tracing 的 ANSI 输出,重定向到文件时会变成一堆转义字符。生产环境要么用支持颜色的日志查看器,要么在 tracing_subscriber 初始化时关掉 ANSI。本文一律展示去掉颜色码之后的可读版本,所以你实际看到的行首会多几个控制字符,那不是乱码。

边界与代价

先讲构建。上面的 2 分 03 秒是 debug 构建、冷依赖的数字;50.73 秒是改代码后的增量数字。这两个数字只代表这台机器和这个依赖集合,换机器、加依赖、开 lto 都会变。release 构建的产物体积和启动耗时我没有在本机实测,不写成结论。能给的判断是:debug 构建编译快、运行慢,适合开发;release 构建编译慢、运行快,适合交付。不要拿 debug 二进制去压测,更不要用它判断线上性能。

再讲「薄框架」的代价。Axum 只负责路由、提取器和响应,它不提供 ORM、认证、会话、后台任务调度、管理后台。项目一旦超过「几个接口」的规模,这些都要自己选型并拼起来。好处是每一层都能换、行为可解释;坏处是起步时看起来文件很多,团队新人要先把这套拼装逻辑学一遍。本文后面五篇,本质上就是在补这五块拼图。

和 Actix 的取舍也一样。Actix 更像「给你一套已经装好的框架」,worker 模型、状态管理、中间件都有既定答案;Axum 更像「给你一套积木和一套类型约束」。如果团队追求快速交付、且不需要复用 tower 生态,Actix 的默认答案更省心;如果系统要和 tokio 生态深度集成、或者中间件需要跨语言、跨框架复用,Axum 的薄更有价值。没有哪一边绝对更好。

还有一个现实边界:单进程服务的能力受限于一台机器。这里没有引入任何分布式组件,SQLite 也是本地文件。用户量上来以后,连接池、后台任务、部署方式都会成为瓶颈,这些分别在第 3、5、6 篇处理。起步阶段不要提前上集群,先把一个进程跑稳,比一上来就拆服务更能暴露真实问题。

如果只是在本机验证,127.0.0.1 就够了;要让局域网里的手机访问,需要绑 0.0.0.0,同时确认 Windows 防火墙放行。这个改动只影响监听地址,不影响路由和状态,别把它和「服务起不来」混为一谈。

很多团队在这一步就急着上 Docker 和 CI,结果是本地还没跑通,先在镜像里排查网络。顺序应该反过来:本机能稳定启动、curl 能拿到预期 JSON、重启后行为一致,再考虑打包。那 2 分 03 秒的构建时间会随着依赖增加继续变长,CI 里把 cargo 的缓存目录存下来,能省掉大部分冷编译;本机则要接受它,别为了「快一点」去删依赖。

当天能自己验证的练习

  1. 在空目录执行 cargo new rustdemo,按上面的依赖清单写 Cargo.toml,跑一次 cargo build 并记录耗时;再改一行注释跑第二次,对比两次时间,理解「冷依赖」和「增量」的区别。
  2. 故意把路由改成 /api/items/:id,请求 /api/items/1,确认返回 404;再改成 /api/items/{id} 并补一个返回固定 JSON 的处理函数,确认 200。
  3. 删掉 .with_state(state) 这一行,把编译错误原文抄下来,找到其中的 State 与 trait bound 关键词,然后恢复。
  4. 保留一个正在运行的实例,再开一个终端执行 cargo run,复现 os error 10048,用 netstat -ano | findstr :18080 找到占用进程。
  5. 把 uptime_secs 打印出来,启动后立刻请求一次、等 30 秒再请求一次,确认数字变化;再把 SQLite URL 改成不带 mode=rwc 且删掉 app.db,观察启动错误。

这五个练习都不需要改业务逻辑,目的是把「构建、路由、状态、端口、数据库文件」五件事各自独立地验证一遍。做完之后,再遇到 404 或启动失败,你至少能判断问题在哪一层,而不是从头重写。

下一篇进入请求内部。一个请求从进入进程到离开,会依次经过全局中间件、路由匹配、提取器、处理函数和响应转换;提取器的顺序、body 只能被消费一次、中间件该放在哪一层,这些决定了很多「看起来是业务 bug」的问题。路由和分层那一篇会把这些拆开,并解释为什么权限判断不应该写在处理函数里。

小结

三句话收束:Axum 是 hyper 加 tower 之上的一层薄框架,处理函数是普通 async 函数,状态用 with_state 注入;#[tokio::main] 提供运行时,axum::serve 使用运行时,两者缺一不可;起步阶段最常见的故障是 0.8 的 {id} 语法、忘记 with_state、端口 10048 和 SQLite 少了 mode=rwc。

把这篇的工程留着,下一篇会直接在这个 main.rs 上长出路由分层、提取器和中间件。不要重开项目,增量构建会让后面的验证快很多。