那天的工作是给一个小工具加个 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,请求后 404 | Axum 0.8 的路径参数改用花括号,冒号写法只属于 0.7 | 看 route 里参数那一截,改成 {id} |
编译报 State 相关的 trait bound 不满足 | 用了 State<AppState> 提取器,但 Router 末尾没有 .with_state | 看路由链最后一行有没有把状态喂进去 |
启动报 os error 10048 | Windows 上端口已被占用,10048 就是「地址已被使用」 | netstat -ano | findstr :18080 找到进程号 |
改一行代码,cargo run 又要等很久 | debug 构建加依赖重编,首次和增量是两回事 | 确认是不是改了 Cargo.toml 触发全量依赖重编 |
| 路由明明写了,curl 仍 404 | HTTP 方法不匹配,例如路由是 POST,请求发的是 GET | 用 curl -i 看清状态码和请求方法 |
| 返回 415,body 解析失败 | 请求没有带 Content-Type: application/json | curl 加上 -H "Content-Type: application/json" |
| 接口 500,控制台却什么都没有 | 处理函数 panic,且没有装日志与 panic 输出 | 看 stderr 原始输出,先接上 tracing |
健康检查里 db 是 false | SQLite 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"] }
目录先保持最小。后面几篇会往里加文件,但起步阶段不要一次性铺开分层,否则连「哪个文件在跑」都说不清:
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_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 的缓存目录存下来,能省掉大部分冷编译;本机则要接受它,别为了「快一点」去删依赖。
当天能自己验证的练习
- 在空目录执行
cargo new rustdemo,按上面的依赖清单写Cargo.toml,跑一次cargo build并记录耗时;再改一行注释跑第二次,对比两次时间,理解「冷依赖」和「增量」的区别。 - 故意把路由改成
/api/items/:id,请求/api/items/1,确认返回 404;再改成/api/items/{id}并补一个返回固定 JSON 的处理函数,确认 200。 - 删掉
.with_state(state)这一行,把编译错误原文抄下来,找到其中的State与 trait bound 关键词,然后恢复。 - 保留一个正在运行的实例,再开一个终端执行
cargo run,复现os error 10048,用netstat -ano | findstr :18080找到占用进程。 - 把
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 上长出路由分层、提取器和中间件。不要重开项目,增量构建会让后面的验证快很多。