罗罗编程学习记录
本页内容 展开查看

04.4.4.1 App路由与提取器

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.4 Actix Web

04.4.4.1-001 App 在 actix-web 中承担什么角色?

一句话结论

App 是 actix-web 的路由、中间件与应用数据的注册容器,等价于一棵可挂载资源与子作用域的服务装配树;HttpServer 按 worker 复制这份装配对外提供服务。

概念解释

App 本身不直接监听端口,它定义「有哪些路由、挂了哪些中间件、注入了哪些共享数据」。路由以 Resource 为单位注册,资源下再挂按方法匹配的路由项;scope 提供前缀分组。理解 App 的容器属性,才能分清数据、中间件、路由各自挂在哪一层。

原理流程

  1. App::new() 建立空装配容器。
  2. 链式调用注册资源、作用域、中间件与数据。
  3. HttpServer::new 的闭包返回装配好的 App。
  4. 每个 worker 持有一份 App 副本处理请求。

代码或图示

use actix_web::{App, HttpServer, web, HttpResponse};

async fn index() -> HttpResponse {
    HttpResponse::Ok().body("hi")
}

let app = App::new().service(web::resource("/").route(web::get().to(index)));

常见误区

  • 以为 App 直接绑定端口:绑定由 HttpServer 完成,App 只做装配。
  • 在 App 注册完成后再动态追加路由,运行期路由表不再变更。

追问

  • App 与 scope 是什么关系?答:scope 是带前缀的子装配单元,资源与中间件挂在 scope 下只作用于该前缀。
  • App 注册的中间件作用范围多大?答:挂在 App 上作用于整棵树;挂在 scope 或资源上只作用于对应子树。

04.4.4.1-002 App::new 之后链式注册的对象分别进入哪一层?

一句话结论

.service() 注册资源或子作用域,.wrap() 挂中间件,.app_data() 注入共享数据;链式顺序决定中间件包裹方向与数据可见范围。

概念解释

actix-web 的装配是链式 builder:每个方法返回新的 App 或资源类型。资源路由决定路径与方法匹配,中间件按挂载顺序形成包裹链,数据按类型注入供提取器取用。新增接口时先确认挂在 App、scope 还是资源层,避免作用域错误。

原理流程

  1. App::new() 得到空容器。
  2. 注册 web::resource、web::scope 等服务项。
  3. 链式 wrap 追加中间件层。
  4. app_data 注入类型化共享数据。

代码或图示

App::new()
    .wrap(actix_web::middleware::Logger::default())
    .app_data(web::Data::new(AppState { counter: 0 }))
    .service(web::scope("/api").service(web::resource("/items").route(web::get().to(list))))

常见误区

  • 把中间件挂到资源层却期望全局生效。
  • 数据注入类型与提取器类型不一致,提取时取不到。

追问

  • .service() 能直接传 handler 函数吗?答:可以,带路由宏的 handler 可作为 service 注册;具体注册形式以 docs.rs 当前版本为准。
  • 链式调用返回类型会变吗?答:资源上的链式方法返回资源类型,App 层返回 App;跨层调用需在正确类型上继续。

04.4.4.1-003 为什么 HttpServer::new 接收一个返回 App 的闭包?

一句话结论

工厂闭包在每个 worker 启动时被调用一次,生成独立的 App 副本;这样各 worker 持有自己的装配与中间件实例,共享数据则通过 web::Data 句柄跨 worker 共享。

概念解释

actix-web 多 worker 模型下,App 装配不能只构造一次被所有线程共享,否则中间件状态与路由装配的所有权约束难以满足。闭包每次返回新 App,Data 内部是原子引用计数句柄,真正共享的是句柄指向的数据。闭包捕获的内容必须满足跨线程与 'static 约束。

原理流程

  1. HttpServer::new(|| App::new()...) 传入工厂闭包。
  2. 每个 worker 启动时调用闭包生成 App。
  3. 中间件、路由表在各 worker 副本内独立存在。
  4. Data 句柄内部共享底层数据。

代码或图示

HttpServer::new(|| {
    App::new()
        .app_data(web::Data::new(shared_state.clone()))
        .service(web::resource("/").route(web::get().to(index)))
})
.bind(("127.0.0.1", 8080))?
.workers(4)
.run()
.await?;

常见误区

  • 把需要每 worker 独立的状态放进 Data,导致各 worker 共享了本应隔离的实例。
  • 闭包捕获非 Send 的局部引用,编译期跨线程约束报错。

追问

  • 工厂闭包多久调用一次?答:按 worker 数量在启动阶段各调用一次;worker 数调整会改变副本数量。
  • App 副本之间路由表重复存储有开销吗?答:路由表在各 worker 独立持有,内存随 worker 数增长;常规规模下不是瓶颈。

04.4.4.1-004 bind 如何绑定监听地址,绑定失败有哪些表现?

一句话结论

HttpServer::bind((host, port)) 把服务绑定到指定地址端口,端口占用、地址不可用或权限不足时返回错误,启动阶段即暴露而不是运行期崩溃。

概念解释

绑定参数是 (impl Into<String>, u16) 形式的地址端口对。容器部署常需绑定 0.0.0.0 才能被外部访问;绑定 127.0.0.1 仅本机可达。低于 1024 的端口在部分系统需要特权。绑定失败错误沿 ? 传播到 main,进程以非零退出。

原理流程

  1. 解析监听地址与端口。
  2. 创建 socket 并尝试 bind。
  3. 成功则进入 listen 与 worker 启动。
  4. 失败返回绑定错误,main 退出。

代码或图示

HttpServer::new(|| App::new())
    .bind(("0.0.0.0", 8080))?
    .run()
    .await?;

常见误区

  • 容器内绑 127.0.0.1,外部健康检查不通。
  • 端口被残留进程占用,新实例绑定失败被误判为代码问题。

追问

  • 如何绑定多个端口?答:链式多次调用 bind,服务在所有绑定地址上监听;具体 API 以 docs.rs 当前版本为准。
  • 绑定失败错误类型是什么?答:返回 actix 启动错误,包装底层 IO 错误;错误链可通过 source 追溯。

04.4.4.1-005 workers 参数如何设置,默认依据是什么?

一句话结论

.workers(n) 指定 worker 线程数,默认通常按 CPU 逻辑核数取值;调整依据是 CPU 密集程度、IO 占比与部署规格,不是越大越好。

概念解释

worker 是服务请求的调度单元,actix-web 基于异步处理,单个 worker 可并发处理大量 IO 请求。CPU 密集 handler 需要更多 worker,IO 密集场景过多 worker 反而增加调度与上下文开销。容器环境要注意分配的 CPU 配额与宿主机核数不一致。

原理流程

  1. 读取配置的 worker 数或使用默认值。
  2. 按数量启动 worker 调度单元。
  3. 连接在 worker 间分配。
  4. 各 worker 独立处理请求生命周期。

代码或图示

HttpServer::new(|| App::new())
    .bind(("127.0.0.1", 8080))?
    .workers(4)
    .run()
    .await?;

常见误区

  • 盲目把 worker 设成超大值,上下文切换开销压过并发收益。
  • 容器只分配 1 核却沿用宿主机核数默认值,调度抖动。

追问

  • worker 数与 Tokio 线程数是一回事吗?答:actix-web 的 worker 模型与底层运行时调度相关,具体对应关系以 actix-rt/actix-web 文档当前版本为准。
  • IO 密集服务 worker 怎么调?答:先按默认压测,观察等待时间与 CPU 利用率,再小幅调整。

04.4.4.1-006 shutdown_timeout 控制什么?

一句话结论

.shutdown_timeout(secs) 设定优雅停机等待在途请求收尾的秒数,超时后强制终止剩余连接;与负载均衡摘流配合避免请求被硬切。

概念解释

收到停机信号后,服务停止接收新连接,给在途请求预留处理窗口。超时阈值要覆盖最长的正常请求耗时;后台任务、长连接(WebSocket/SSE)需要单独的取消与等待逻辑。超时设置过短会截断事务,过长会拖慢发布流程。

原理流程

  1. 进程收到停机信号。
  2. 停止 accept 新连接。
  3. 等待在途请求与任务收尾,计时开始。
  4. 超时未排空则强制关闭,进程退出。

代码或图示

HttpServer::new(|| App::new())
    .bind(("127.0.0.1", 8080))?
    .shutdown_timeout(30)
    .run()
    .await?;

常见误区

  • 只设应用超时,未对齐网关摘流与容器终止宽限时间。
  • 长轮询/ WebSocket 连接被计入在途,停机长时间不退出。

追问

  • 后台定时任务如何响应停机?答:监听关闭信号或在服务生命周期钩子中取消循环;具体钩子 API 以 docs.rs 当前版本为准。
  • shutdown_timeout 单位是什么?答:秒;参数类型与默认值以文档当前版本为准。

04.4.4.1-007 HttpServer::run 返回什么,main 中如何等待服务结束?

一句话结论

run() 返回一个可 await 的服务运行句柄,main 中 .await 阻塞等待直到服务停机;启动失败通过 ? 提前传播错误。

概念解释

actix-web 服务是异步运行的长任务,run() 启动 worker 与监听循环后返回控制句柄。main 用 await 挂起当前线程等待服务结束;期间信号处理、停机流程由运行时与服务协作完成。错误处理遵循 Result 传播,不要在 main 里吞掉启动错误。

原理流程

  1. 完成 App 装配与 bind。
  2. run() 启动监听与 worker,返回运行句柄。
  3. main await 句柄等待服务结束。
  4. 正常停机返回 Ok,启动/运行错误沿错误链返回。

代码或图示

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| App::new())
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

常见误区

  • 调用 run() 后不 await,main 直接退出导致服务未真正启动。
  • 忽略 ?,绑定失败时进程仍正常退出,排查方向错误。

追问

  • 服务运行句柄能中途获取地址信息吗?答:运行句柄提供查询监听地址等方法;具体方法集以 docs.rs 当前版本为准。
  • 如何在运行期触发停机?答:通过信号处理或句柄的停止方法;具体 API 按当前版本文档核对。

04.4.4.1-008 #[actix_web::main] 宏做了什么?

一句话结论

该宏把 async fn main 包装为 actix-rt 运行时入口,建立异步执行器并驱动 main 中的 Future 完成;等价于手动启动运行时再 block_on。

概念解释

Rust 标准库 main 不能是 async,需要运行时入口宏把异步 main 接入执行器。#[actix_web::main] 内部使用 actix-rt 运行时,actix-web 的 handler、服务句柄都在该运行时上调度。熟悉 Tokio 的开发者可对照 #[tokio::main] 理解,但二者运行时实现不同,不要混用假设。

原理流程

  1. 宏展开为同步 main 函数。
  2. 初始化 actix-rt 运行时。
  3. 在运行时上 block_on 异步 main 体。
  4. 服务 Future 被调度执行直到停机。

代码或图示

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // 异步服务在此启动并被驱动
    HttpServer::new(|| App::new()).bind(("127.0.0.1", 8080))?.run().await
}

常见误区

  • 在 actix 运行时里直接调用 Tokio 专属运行时 API 而不确认兼容性。
  • 把同步阻塞计算写进 main 异步体,卡住运行时启动。

追问

  • 能否不用宏手动建运行时?答:可以按 actix-rt 文档手动构造运行时并阻塞执行;常规项目直接用宏。
  • actix-web 与 Tokio Future 是否兼容?答:Future 抽象层面互通,具体运行时特性以 actix-rt 当前版本文档为准。

04.4.4.1-009 多 worker 下 App 副本与共享数据如何隔离?

一句话结论

路由表、中间件实例在各 worker 的 App 副本内独立;需要跨 worker 共享的数据通过 web::Data 包装,内部用线程安全句柄共享底层值。

概念解释

判断状态归属:每 worker 独立的中间件计数器可放在中间件实例内;全实例共享的配置、连接池、缓存必须进 Data。worker 间不共享 App 内的普通结构体字段,直接在 App 上挂可变状态不会跨 worker 累积。

原理流程

  1. 工厂闭包为每个 worker 生成 App。
  2. 中间件与路由表随副本独立存在。
  3. Data 句柄克隆到各副本,指向同一底层数据。
  4. 并发访问共享数据由内部同步机制保护。

代码或图示

let state = web::Data::new(AppState { counter: 0 });

HttpServer::new(move || {
    App::new()
        .app_data(state.clone())
        .service(web::resource("/").route(web::get().to(handler)))
})

常见误区

  • 以为 App 上挂的普通字段在 worker 间共享,计数永远不累积。
  • Data 内放非线程安全类型,跨 worker 编译或运行期出问题。

追问

  • Data::new 内部用什么实现共享?答:基于原子引用计数的共享句柄;具体类型实现以 docs.rs 当前版本为准。
  • 需要每 worker 独立缓存怎么做?答:放在中间件或 worker 局部结构中,不要包进 Data。

04.4.4.1-010 actix-web 注册路由有哪三类入口?

一句话结论

三类入口:web::resource 精确路径资源、web::scope 前缀子树、带路由宏的 handler 直接 service 注册;分别对应单路径、分组与宏驱动场景。

概念解释

resource 绑定一个路径模板并在其上挂方法路由;scope 拼前缀并组织子资源;宏路由(#[get("/")] 等)修饰 handler 后可直接作为 service 注册。选择哪类取决于路由规模与分组需求,大型项目常用 scope 划分业务模块。

原理流程

  1. 按模块边界选择 scope 前缀。
  2. 在 scope 内注册 resource 与方法路由。
  3. 宏 handler 作为 service 挂载。
  4. 路由表在 App 副本内建立匹配结构。

代码或图示

App::new()
    .service(
        web::scope("/api")
            .service(web::resource("/items").route(web::get().to(list)))
    )
    .service(hello_macro) // #[get("/hello")] 修饰的 handler

常见误区

  • scope 前缀与 resource 路径拼接重复或遗漏斜杠,最终路径与预期不符。
  • 把分组中间件挂在 App 层,超出了预期作用域。

追问

  • web::route() 与 web::resource() 区别?答:resource 是路径容器,route 是资源上的方法路由注册入口;层级不同。
  • 宏路由注册需要手动写路径吗?答:路径写在宏属性里,注册时不再重复;宏与手写 resource 可混用。

04.4.4.1-011 App 级 wrap 中间件如何挂载,包裹方向是什么?

一句话结论

.wrap(middleware) 在 App 装配链上追加一层中间件,先挂载的在外层、后挂载的在内层;请求从外到内进入,响应从内到外返回。

概念解释

中间件形成洋葱模型:日志、CORS 这类通用层通常挂外层,业务处理在内层。wrap 顺序影响响应头加工与错误捕获范围。actix-web 内置 Logger、Compress、DefaultHeaders 等中间件,自定义中间件实现对应 trait。

原理流程

  1. App 装配时按链式顺序记录 wrap 层。
  2. 请求进入时由外层向内层穿过。
  3. handler 产出响应后由内层向外层返回。
  4. 每层可在请求前后加工上下文与响应。

代码或图示

App::new()
    .wrap(actix_web::middleware::Logger::default())
    .wrap(actix_web::middleware::DefaultHeaders::new().add(("X-App", "ann")))
    .service(web::resource("/").route(web::get().to(index)))

常见误区

  • 以为后挂载的中间件在外层,错误判断日志与头的加工顺序。
  • 中间件在 scope 与 App 重复挂载,逻辑执行两次。

追问

  • 中间件能访问提取器参数吗?答:中间件作用于服务层,类型化参数在 handler 提取;跨层传递通过请求扩展或数据注入。
  • 内置中间件有哪些常用项?答:Logger、Compress、DefaultHeaders、NormalizePath 等;完整清单以 docs.rs 当前版本为准。

04.4.4.1-012 app_data 注入的数据如何被提取器取用?

一句话结论

.app_data(web::Data::new(value)) 把类型化句柄注入 App,handler 参数 web::Data<T> 提取同一实例;按类型匹配,类型不一致则提取失败。

概念解释

数据注册与提取是类型闭环:注册时的包装类型必须与提取参数类型一致。app_data 也可直接插入未包装的值,由对应提取器取用;Data 是最常用的共享句柄形式。配置、连接池、缓存句柄都走这一入口。

原理流程

  1. 构造共享值并包装为 Data。
  2. App 或 scope 层 app_data 注入。
  3. handler 参数声明 Data<T>。
  4. 提取器按类型从注入表取出句柄。

代码或图示

#[derive(Clone)]
struct AppState { name: String }

async fn handler(data: web::Data<AppState>) -> String {
    data.name.clone()
}

App::new()
    .app_data(web::Data::new(AppState { name: "ann".into() }))
    .service(web::resource("/").route(web::get().to(handler)))

常见误区

  • 注册 Data<Config>,提取参数写成 Data<Arc<Config>>,类型不匹配。
  • 在 scope 层注入数据却在 scope 外的 handler 提取。

追问

  • app_data 与 data 方法有区别吗?答:actix-web 提供 app_data 直接插入与旧版 data 包装方法;行为差异以 docs.rs 当前版本为准。
  • 同一类型能注入多份吗?答:按类型索引,重复类型会覆盖或冲突;多实例需 newtype 区分。

04.4.4.1-013 web::Data 的克隆语义与内部共享是什么?

一句话结论

Data<T> 是轻量克隆的共享句柄,克隆句柄指向同一底层 T;底层值通常要求线程安全,句柄本身可跨 worker 与 handler 传递。

概念解释

Data 解引用到 T,handler 内通过 data.0 或 Deref 访问字段。需要内部可变时,T 内部用 Mutex/RwLock/原子类型保护;不要试图通过 Data<&mut T> 获得可变借用。句柄克隆成本低,工厂闭包中 move 克隆即可。

原理流程

  1. Data::new(value) 构造共享句柄。
  2. 句柄克隆进入各 App 副本与 handler 参数。
  3. 通过 Deref 读取底层值。
  4. 内部可变操作经同步原语完成。

代码或图示

use std::sync::atomic::{AtomicU64, Ordering};

struct Counter(AtomicU64);

async fn hit(data: web::Data<Counter>) -> String {
    data.0.fetch_add(1, Ordering::Relaxed);
    data.0.load(Ordering::Relaxed).to_string()
}

常见误区

  • 对 Data<T> 直接字段赋值,违反共享借用规则。
  • 底层类型不含同步保护,多 worker 并发修改产生数据竞争(编译期多数能拦截)。

追问

  • Data 解引用目标是什么?答:Data<T> Deref 到 T;访问内部字段按 data.field 写法。
  • 连接池为什么适合放 Data?答:池句柄内部线程安全且可克隆共享,各请求从池内借出连接,符合 Data 模型。

04.4.4.1-014 actix-web 的请求处理是异步 actor 模型还是 Future 模型?

一句话结论

actix-web 基于 actix 运行时的 worker 调度与 Rust Future 异步处理,handler 是返回 Future 的异步函数;可理解为 actor 式隔离的 worker 上跑异步任务。

概念解释

actix 生态早期以 actor 模型著称,actix-web 的服务调度保留了 worker 隔离与消息驱动的结构,但业务 handler 写法是标准 async/await Future。面试作答应区分:底层调度模型与业务代码模型,不要把 handler 写成传统 actor 消息处理。

原理流程

  1. worker 调度单元接收连接。
  2. 请求处理流程以 Future 提交执行。
  3. 异步 IO 等待时让出调度权。
  4. 完成后生成响应写回。

代码或图示

async fn handler(_req: actix_web::HttpRequest) -> HttpResponse {
    HttpResponse::Ok().body("async handler")
}

常见误区

  • 把 handler 设计成持有 actor 地址再转发消息的重结构,增加不必要复杂度。
  • 在异步 handler 里做阻塞等待,占用 worker 调度能力。

追问

  • actix-web 与纯 Tokio 服务在调度上差在哪?答:worker 隔离结构与 actix 运行时集成;具体实现以当前版本文档为准。
  • 业务需要后台 actor 怎么办?答:可引入 actix Actor 与服务地址,与 Web handler 通过消息通信;属于扩展设计。

04.4.4.1-015 在异步 handler 中做阻塞调用有什么风险,如何隔离?

一句话结论

异步 handler 内的同步阻塞 IO 或 CPU 密集计算会卡住 worker 调度,降低整体并发;阻塞任务应放到独立阻塞线程池执行,再把结果交回异步流程。

概念解释

异步运行时靠任务让出等待来复用线程,阻塞调用不让出会占住调度单元。文件重 IO、CPU 加解密、同步数据库驱动调用都属于阻塞点。actix 运行时提供阻塞任务调度接口;跨线程返回结果需满足 Send 约束。

原理流程

  1. 识别 handler 中的阻塞操作。
  2. 用阻塞任务接口移出异步线程执行。
  3. 等待阻塞任务句柄返回结果。
  4. 继续异步流程生成响应。

代码或图示

// 阻塞任务隔离示意,具体阻塞 spawn API 以 docs.rs 当前版本为准
async fn handler() -> Result<HttpResponse, actix_web::Error> {
    let result = actix_web::rt::task::spawn_blocking(|| {
        // 同步阻塞计算或 IO
        42
    })
    .await?;
    Ok(HttpResponse::Ok().body(result.to_string()))
}

常见误区

  • 在 handler 里调用同步数据库驱动并 .lock() 长等待。
  • 阻塞任务内捕获不可跨线程的数据,编译报错。

追问

  • 怎么判断 handler 是否阻塞?答:压测观察 worker 利用率与吞吐,CPU 打满但请求排队说明阻塞占住调度。
  • spawn_blocking 返回的错误要处理什么?答:任务 panicked 或取消会返回 Join 错误,需包装为 Web 错误响应。

04.4.4.1-016 服务如何同时监听多个地址或端口?

一句话结论

在 HttpServer 上链式多次调用 bind,服务在所有已绑定地址上接受连接;各绑定共享同一 App 装配与 worker 配置。

概念解释

多端口常见于业务端口与健康检查端口分离、IPv4/IPv6 双栈等场景。绑定顺序与错误处理:任一 bind 失败都会沿 ? 中止启动。多个绑定地址共用同一套路由与中间件,不需要重复构造 App。

原理流程

  1. 构造 HttpServer 与 App 工厂。
  2. 依次 bind 各地址端口。
  3. 监听 socket 全部注册到服务。
  4. run() 后在所有地址上接收请求。

代码或图示

HttpServer::new(|| App::new())
    .bind(("0.0.0.0", 8080))?
    .bind(("0.0.0.0", 8081))?
    .run()
    .await?;

常见误区

  • 以为多端口需要启动多个 HttpServer 实例。
  • 第二个 bind 失败未用 ? 传播,服务只监听部分地址。

追问

  • 不同端口需要不同路由怎么办?答:单实例装配难以按端口分流,可在中间件按连接地址判断,或拆多个服务实例。
  • IPv6 绑定怎么写?答:地址用 IPv6 字面量;系统与防火墙需放开对应协议族。

04.4.4.1-017 服务启动时配置读取与装配的顺序是什么?

一句话结论

先读取外部配置并构造共享状态,再注入 App 工厂,最后 HttpServer 绑定启动;配置缺失应在启动早期 fail-fast,而不是请求期才暴露。

概念解释

典型顺序:解析环境变量/配置文件 → 构造连接池与配置结构体 → 包装 Data → 传入 App 工厂 → bind 与 run。启动期校验必填配置,避免请求运行到一半才发现缺依赖。配置结构体设计为类型安全,注册进 Data 供 handler 读取。

原理流程

  1. 加载并校验配置。
  2. 初始化外部依赖句柄(池、客户端)。
  3. 包装 Data 并注册。
  4. HttpServer 装配、绑定、运行。

代码或图示

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let cfg = AppConfig::load()?; // 启动期校验
    let data = web::Data::new(cfg);

    HttpServer::new(move || App::new().app_data(data.clone()).service(route::index()))
        .bind(("0.0.0.0", 8080))?
        .run()
        .await
}

常见误区

  • 在第一个请求里懒加载配置,冷启动请求超时且并发下重复初始化。
  • 配置字符串散落读取,进入 handler 才发现格式错误。

追问

  • 启动期依赖不可达应该退出还是继续?答:核心依赖 fail-fast;可降级旁路允许后续重试,按业务定。
  • 配置结构体需要 Clone 吗?答:放入 Data 的值建议可克隆或为共享句柄;工厂闭包克隆句柄进各副本。

04.4.4.1-018 优雅停机在 actix-web 中经历哪些阶段?

一句话结论

停机信号到达后停止 accept 新连接,等待在途请求与后台任务收尾(受 shutdown_timeout 约束),释放资源后退出;长连接需显式取消。

概念解释

优雅停机要与部署编排配合:负载均衡先摘流,再发停止信号,应用排空后退出。WebSocket、SSE 等长连接不会随普通请求自然结束,需要在停机流程中断开。后台任务、定时循环要监听取消信号。

原理流程

  1. 收到 SIGTERM 类信号。
  2. 服务停止接收新连接。
  3. 在途请求处理完成或超时。
  4. 取消长连接与后台任务,释放资源退出。

代码或图示

摘流 → 停止 accept → 等待在途请求/任务
  → 断开长连接 → 释放资源 → 进程退出
超时:强制终止剩余连接

常见误区

  • 只等 HTTP 请求,忘记后台任务仍在写入。
  • 应用退出快于网关摘流,发布窗口出现连接拒绝。

追问

  • 如何在停机时保存状态?答:在关闭钩子中 flush 日志与队列;钩子可用方式以 docs.rs 当前版本为准。
  • 长连接断开通知客户端吗?答:应主动关闭并发送关闭帧,避免客户端半开等待。

04.4.4.1-019 内置 Logger 中间件默认记录什么?

一句话结论

Logger 中间件按格式记录请求方法、路径、响应状态、耗时等访问日志,默认格式覆盖常见排查字段;格式串可定制。

概念解释

Logger 是最常用的 App 级中间件,输出访问日志而非业务调试日志。默认格式包含方法、URI、状态码、处理耗时等;敏感查询参数是否记录需按安全要求评估。生产环境通常把日志接入结构化采集。

原理流程

  1. App 装配时 .wrap(Logger::default())。
  2. 请求进入记录开始上下文。
  3. 响应返回后计算状态与耗时。
  4. 按格式串输出访问日志。

代码或图示

use actix_web::middleware::Logger;

App::new()
    .wrap(Logger::new("%a %r %s %T"))
    .service(web::resource("/").route(web::get().to(index)))

常见误区

  • 用 Logger 输出业务错误详情,职责与访问日志混淆。
  • 日志包含 Authorization、Cookie 等敏感头。

追问

  • Logger 格式占位符有哪些?答:方法、路径、状态、耗时、远端地址等;完整占位符清单以 docs.rs 当前版本为准。
  • 访问日志与 tracing 如何配合?答:Logger 负责 HTTP 层访问记录,业务链路追踪用 tracing 体系,二者字段可关联。

04.4.4.1-020 如何自定义默认 404 响应?

一句话结论

未匹配路由的默认响应可通过 App 级默认服务或错误处理覆盖,返回结构化 JSON 或自定义页面;默认行为是通用 404 响应。

概念解释

actix-web 路由表未命中时走默认服务,默认输出 404 响应。接口项目通常希望 404 也返回统一错误 JSON,与业务错误格式一致。自定义方式包括注册默认资源、配置错误处理器等,具体 API 以当前版本文档为准。

原理流程

  1. 请求路径遍历路由表未命中。
  2. 进入默认服务处理。
  3. 自定义处理器生成统一错误响应。
  4. 写出 404 状态与错误体。

代码或图示

// 示意:默认服务返回 JSON 404,具体注册 API 以 docs.rs 当前版本为准
async fn not_found() -> actix_web::HttpResponse {
    actix_web::HttpResponse::NotFound()
        .json(serde_json::json!({ "error": "not_found" }))
}

常见误区

  • 各 handler 自行返回 404,错误格式不统一。
  • 覆盖默认服务后漏挂静态资源路由,资源 404 被 JSON 接管。

追问

  • 404 与 405 在 actix-web 中如何区分?答:路径未命中为 404;路径命中但方法守卫不匹配,按路由表继续匹配或落到 405/404,具体行为以文档为准。
  • 自定义 404 能区分 API 与页面路径吗?答:可在处理器内按路径前缀判断返回 JSON 或 HTML。

04.4.4.1-021 Error 与 ResponseError 在错误处理中是什么关系?

一句话结论

actix_web::Error 是 Web 层通用错误包装,ResponseError trait 规定错误类型如何转成 HttpResponse;自定义错误实现该 trait 即可在 handler 中用 ? 传播。

概念解释

handler 返回 Result<impl Responder, Error>,业务错误类型实现 ResponseError::error_response 生成状态码与 body。Error::from 把实现了 ResponseError 的类型包进通用错误。错误类型与序列化错误、提取器错误在此汇合为 Web 响应。

原理流程

  1. 业务错误类型实现 ResponseError。
  2. handler 用 ? 返回错误,经 Error::from 包装。
  3. 服务调用 error_response 生成响应。
  4. 按状态码写出错误体。

代码或图示

#[derive(thiserror::Error, Debug)]
enum BizError {
    #[error("not found")]
    NotFound,
}

impl actix_web::ResponseError for BizError {
    fn error_response(&self) -> actix_web::HttpResponse {
        actix_web::HttpResponse::NotFound().json(serde_json::json!({ "error": self.to_string() }))
    }
}

常见误区

  • 自定义错误只实现 Error trait 没有实现 ResponseError,无法转成响应。
  • 错误响应直接暴露内部堆栈或数据库细节。

追问

  • ResponseError 必须返回 JSON 吗?答:返回任意 HttpResponse,HTML、文本均可;按接口风格选择。
  • 提取器解析失败返回什么错误?答:提取器返回自己的 Rejection/错误类型,经 Web 错误层映射为 400 类响应。

04.4.4.1-022 handler 返回值如何满足 Responder 约束?

一句话结论

handler 返回类型需实现 Responder(可转换为响应),内置 HttpResponse、String、Json、元组与部分状态类型都已实现;自定义类型可实现该 trait。

概念解释

actix-web 通过 Responder 抽象把 handler 产出物变成 HTTP 响应。返回 HttpResponse 最直接;返回 web::Json<T> 需要 T: Serialize。Result 只要成功与错误类型都实现 Responder 即可。返回值类型不满足约束会在编译期报错。

原理流程

  1. handler 声明返回类型。
  2. 服务调用该类型的 Responder 实现。
  3. 生成状态码、头部与 body。
  4. 响应经过中间件链写出。

代码或图示

async fn text() -> String { "hello".into() }

async fn json() -> actix_web::web::Json<serde_json::Value> {
    actix_web::web::Json(serde_json::json!({ "ok": true }))
}

async fn via_response() -> actix_web::HttpResponse {
    actix_web::HttpResponse::Ok().body("ok")
}

常见误区

  • 返回未包装的内部结构体,未实现 Responder 导致编译失败。
  • 把 Result<T, E> 的 E 设为普通字符串,未实现响应转换。

追问

  • HttpResponse::Ok().json(...) 与返回 web::Json 区别?答:前者直接构造完整响应,后者由 Responder 包装序列化;二者 Content-Type 均为 JSON。
  • 如何为自定义 DTO 实现 Responder?答:实现 trait 内方法转换为 HttpResponse;具体 trait 签名以 docs.rs 当前版本为准。

04.4.4.1-023 测试服务如何用 test::init_service 启动?

一句话结论

测试中 test::init_service(app) 把 App 装配成可调用的测试服务,不需要真实绑定端口;后续用 test::call_service 发请求断言响应。

概念解释

集成测试在内存中构造服务实例,绕过网络监听。初始化阶段完成路由装配、数据注入与中间件挂载,与生产 App 保持同一装配代码,避免测试与生产分叉。测试服务实例按用例独立构造,状态不串用。

原理流程

  1. 构造测试用 App,注入测试数据。
  2. init_service 初始化服务实例。
  3. TestRequest 构造请求并 call_service 调用。
  4. 断言响应状态、头与 body。

代码或图示

use actix_web::{test, App, web, HttpResponse};

async fn smoke() {
    let app = test::init_service(
        App::new().service(web::resource("/").route(web::get().to(|| async { HttpResponse::Ok().body("ok") })))
    ).await;
    let req = test::TestRequest::get().uri("/").to_request();
    let resp = test::call_service(&app, req).await;
    assert_eq!(resp.status(), actix_web::http::StatusCode::OK);
}

常见误区

  • 测试 App 与生产装配分叉,修了生产路由测试不覆盖。
  • 用例间复用服务实例,共享状态污染断言。

追问

  • init_service 需要绑定端口吗?答:不需要,测试服务在内部处理请求;这是测试工具与 HttpServer 的区别。
  • 测试数据如何注入?答:与生产一样 app_data(web::Data::new(...)),用内存 Mock 替换外部依赖。

04.4.4.1-024 actix-web 依赖如何声明,版本策略注意什么?

一句话结论

Cargo.toml 声明 actix-web 依赖,版本按 crates.io 当前稳定版填写;TLS、压缩等能力通过对应 feature 或配套 crate 引入,不引入无关依赖。

概念解释

actix-web 主 crate 提供 HTTP 服务核心,TLS 由 rustls/openssl 配套中间件或连接器支持,压缩用 actix-web-lab 或内置压缩能力(按版本)。版本升级要对照 release notes 检查 breaking change;本项目不写死次版本号,版本行为以 docs.rs 当前版本为准。

原理流程

  1. 在 [dependencies] 加入 actix-web。
  2. 按需要启用 TLS、压缩等配套项。
  3. cargo build 解析依赖树。
  4. 升级时查阅变更说明并回归测试。

代码或图示

[dependencies]
actix-web = "4"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

常见误区

  • 一次性引入全部 feature,编译体积与安全面扩大。
  • 跟随最新预发布版本,生产稳定性不足。

追问

  • actix-web 4 与 5 迁移要关注什么?答:路由、提取器 API 与错误类型可能有调整;具体差异以各版本 release notes 为准,标注待确认并在 docs.rs 核对。
  • TLS 终止放在应用还是网关?答:常见做法网关终止 TLS,应用内部 HTTP;应用内 TLS 按部署架构需要引入。

04.4.4.1-025 综合:从 main 到响应写出在 actix-web 中经过哪些环节?

一句话结论

链路为:运行时入口 → 配置与共享状态 → App 装配(路由/中间件/数据)→ HttpServer 绑定与 worker 启动 → 路由匹配与提取器构造 → handler 处理 → Responder 生成响应 → 中间件链返回写出。

概念解释

把本批各题串成一条链:main 宏启动运行时,工厂闭包为各 worker 生成 App,请求进入后路由匹配、提取参数,handler 产出经 Responder 成响应,再沿中间件链返回。排错按链路分段:起不来查 bind/配置,路由不到查资源与 guard,参数错查提取器,响应错查 Responder 与中间件。

原理流程

  1. #[actix_web::main] 建立运行时。
  2. 加载配置、构造 Data 共享句柄。
  3. App 工厂注册路由、wrap 中间件、注入数据。
  4. HttpServer bind、起 worker,请求匹配路由并提取参数。
  5. handler 处理,Responder 生成响应,中间件加工后写出。

代码或图示

main 宏 → 配置/State → App 装配
  → HttpServer bind + workers
    → 路由匹配 + 提取器
      → handler
        → Responder → 中间件链 → 响应写出

常见误区

  • 排错只盯 handler,忽略中间件顺序、数据注入类型与路由 guard。
  • 把运行时、worker、handler 三层概念混为一谈。

追问

  • 哪一层决定 Content-Type?答:Responder 按返回类型设置,HttpResponse 可显式覆盖;中间件可补充头但不应无理由改写。
  • 新增接口要检查哪些点?答:资源与方法路由注册、scope 作用域、提取器类型与约束、Data 依赖、错误响应格式与测试断言。

04.4.4.1-026 web::resource 资源对象上能配置哪些内容?

一句话结论

web::resource(path) 是路径容器,可在其上链式注册方法路由、挂载 guard、包裹中间件与命名资源;一个资源对应一个路径模板。

概念解释

资源是 actix-web 路由表的基本单元:路径模板在资源层声明,具体 HTTP 方法处理在资源的 route 列表中。资源级 guard 作用于整个路径,资源级 wrap 只包裹该路径的处理链。把多个方法挂在同一资源下,比重复注册同路径 resource 更清晰。

原理流程

  1. web::resource("/items/{id}") 创建资源。
  2. 链式 .route(web::get().to(h)) 注册方法路由。
  3. 可追加 .guard(...) 与 .wrap(...)。
  4. 资源作为 service 注册进 App 或 scope。

代码或图示

web::resource("/items/{id}")
    .route(web::get().to(get_item))
    .route(web::put().to(update_item))
    .route(web::delete().to(delete_item))

常见误区

  • 同一路径创建多个 resource,方法分散在不同资源,匹配与维护混乱。
  • 在资源上挂全局才需要的中间件,作用域放大。

追问

  • 资源与 scope 嵌套关系是什么?答:scope 提供前缀,资源挂在 scope 下;资源路径相对 scope 前缀拼接。
  • 一个资源能注册两条同方法路由吗?答:同方法应由一条路由处理;多条 guard 分支可按 guard 区分,具体行为以文档为准。

04.4.4.1-027 web::route() 与方法构造器注册路由有什么区别?

一句话结论

web::route() 注册不限定方法的通用路由项,web::get()/post()/... 是预设方法的路由构造器;常用明确方法的构造器,通用 route 用于 guard 组合多方法场景。

概念解释

方法构造器内部就是带方法 guard 的 route。直接用 web::route() 需要自行补充方法或自定义 guard,适合同一 handler 响应多个方法的特殊场景。常规 REST 接口按方法拆分到 get/post/put/delete,语义清晰,405 行为也更可预期。

原理流程

  1. 选择方法构造器或通用 route。
  2. .to(handler) 绑定处理函数。
  3. 路由项进入资源的匹配列表。
  4. 请求方法命中对应路由后调用 handler。

代码或图示

// 明确方法
web::resource("/a").route(web::get().to(h1))

// 通用 route + guard(示意,具体 guard API 以 docs.rs 当前版本为准)
web::resource("/b").route(web::route().guard(guard::Get()).to(h2))

常见误区

  • 用通用 route 不限制方法,POST 请求也走到 GET handler。
  • 同一 handler 挂多方法却不区分权限,越权调用风险。

追问

  • 路由项上的 .to() 接收什么?答:实现 handler trait 的函数或闭包;异步与同步 handler 都支持,具体约束以文档为准。
  • 方法构造器有哪些?答:get、post、put、delete、head、patch、options 等;完整清单以 docs.rs 当前版本为准。

04.4.4.1-028 方法路由构造器返回的路由对象还能做什么配置?

一句话结论

方法路由对象可追加 guard、配置路由级中间件与绑定 handler;它是资源与 handler 之间的中间装配层。

概念解释

路由构造器(如 web::get())返回路由描述,.to(handler) 完成绑定。需要在单方法上额外限制(如仅允许某 Content-Type、自定义请求头)时,在路由层补 guard。路由级配置粒度比资源级更细,避免影响同路径其它方法。

原理流程

  1. 方法构造器生成路由项。
  2. 按需追加路由 guard。
  3. .to() 绑定 handler。
  4. 路由项随资源进入匹配表。

代码或图示

web::resource("/upload")
    .route(web::post().guard(guard::Header("content-type", "multipart/form-data")).to(upload))

常见误区

  • 把只属于某方法的限制挂到资源层,误伤其它方法。
  • 在路由层重复资源层已有的 guard,匹配逻辑冗余。

追问

  • 路由级 wrap 与资源级 wrap 谁先包裹?答:按装配层级由外到内;具体顺序以中间件链文档为准。
  • guard 判断失败会发生什么?答:该路由不匹配,继续尝试资源内其它路由或下一资源。

04.4.4.1-029 web::scope 前缀拼接有哪些规则?

一句话结论

web::scope("/api") 给其子资源统一加路径前缀,子资源路径相对前缀拼接;斜杠处理要保证最终路径规范,避免双斜杠或缺段。

概念解释

scope 是模块化组织手段:按业务域划分前缀,子路由、guard、中间件、数据注入都可限定在 scope 内。前缀与资源路径拼接时以规范路径为准;嵌套 scope 层层叠加前缀。排查 404 时先拼出完整路径再核对路由表。

原理流程

  1. 创建 web::scope(prefix)。
  2. 在 scope 内注册 resource 与子 scope。
  3. 完整路径 = 前缀 + 资源模板。
  4. 请求路径按拼接后的模板匹配。

代码或图示

web::scope("/api/v1")
    .service(web::resource("/items").route(web::get().to(list)))
    // 完整路径:/api/v1/items

常见误区

  • 前缀与子路径都写了首尾斜杠,出现双斜杠导致匹配失败。
  • 以为 scope 只影响文档分组,实际参与路径匹配。

追问

  • scope 中间件作用于哪些请求?答:只作用于匹配该前缀的子树;App 级中间件才覆盖全部。
  • 前缀可以带路径参数吗?答:scope 前缀通常为静态段;动态参数放在资源模板中,具体支持以文档为准。

04.4.4.1-030 scope 内嵌套 scope 如何叠加前缀?

一句话结论

嵌套 scope 的前缀逐层拼接,外层前缀 + 内层前缀 + 资源模板形成最终路径;内层 scope 可独立挂载 guard、中间件与数据。

概念解释

深层模块(如 /admin/v1/orders)用嵌套 scope 表达层级,每层职责清晰。嵌套不改变匹配机制,只是路径叠加与作用域分层。注意内层注入的 Data 只在内层子树可见,外层 handler 取不到。

原理流程

  1. 外层 scope 声明一级前缀。
  2. 内层 scope 在外层 service 链上注册。
  3. 前缀逐层拼接。
  4. 子资源按完整路径匹配。

代码或图示

web::scope("/admin")
    .service(
        web::scope("/v1")
            .service(web::resource("/orders").route(web::get().to(list_orders)))
    )
    // 完整路径:/admin/v1/orders

常见误区

  • 内层 scope 注入的数据被外层 handler 提取,类型注入不可见。
  • 嵌套层级过深,路径拼接关系难以肉眼核对。

追问

  • 嵌套 scope 的中间件顺序如何?答:外层先包裹内层,请求由外到内穿过;响应反向返回。
  • 子 scope 能覆盖外层 guard 吗?答:外层 guard 已在子树之前判定,内层不能绕过;限制应按层级正确放置。

04.4.4.1-031 路由宏(#[get] 等)修饰的 handler 如何注册?

一句话结论

#[get("/path")] 等宏把方法转成可直接 .service() 注册的路由项,路径写在宏属性里;宏 handler 与手写 resource 可在同一 App 混用。

概念解释

宏路由减少样板:方法、路径、handler 绑定一次完成。宏修饰的函数保持普通 async handler 签名,提取器参数照常声明。混用场景下要注意宏路径与手写 resource 不重复注册,避免同路径冲突。

原理流程

  1. 用 #[get("/items/{id}")] 修饰 handler。
  2. 宏生成实现 service trait 的路由项。
  3. App 或 scope 的 .service(handler) 挂载。
  4. 请求按宏声明的方法与路径匹配。

代码或图示

#[actix_web::get("/hello/{name}")]
async fn hello(name: web::Path<String>) -> String {
    format!("hello {name}")
}

App::new().service(hello);

常见误区

  • 宏路径与手写 resource 重复注册同路径,匹配行为不确定。
  • 宏 handler 参数提取器类型写错,编译期才暴露问题。

追问

  • 宏支持哪些方法?答:get、post、put、delete、patch 等;宏属性名以 actix-web 当前版本为准。
  • 宏路由能挂 guard 吗?答:宏侧主要声明方法与路径,复杂 guard 组合更适合手写 resource 链;具体能力以文档为准。

04.4.4.1-032 actix-web 的 guard 体系分哪几类?

一句话结论

guard 是路由匹配的附加判定:方法 guard、路径/头部 guard 与自定义 guard;guard 不通过则该路由不匹配,继续尝试下一项。

概念解释

guard 在路径模板命中后参与判定,回答「这个请求是否归当前路由处理」。内置 guard 覆盖方法、请求头、Host 等条件;复杂业务条件(如特定 token 前缀)实现自定义 guard。guard 只做布尔匹配,不产出类型化参数,参数提取仍由提取器完成。

原理流程

  1. 路径模板初筛得到候选资源/路由。
  2. 逐项运行 guard 判定。
  3. 全部通过则匹配该路由。
  4. 任一 guard 失败则跳过,尝试下一候选。

代码或图示

use actix_web::guard;

web::resource("/search")
    .route(web::get().guard(guard::Header("accept", "application/json")).to(search))

常见误区

  • 把参数校验逻辑写进 guard,guard 无法返回结构化错误。
  • guard 中读取 body,消费后提取器拿不到内容。

追问

  • guard 与提取器职责怎么分?答:guard 做路由级布尔判定;提取器在匹配后构造类型化参数并处理拒绝。
  • 自定义 guard 实现哪个 trait?答:Guard trait,判定方法接收请求上下文;签名以 docs.rs 当前版本为准。

04.4.4.1-033 内置方法 guard 如何判断 HTTP 方法?

一句话结论

guard::Get()、guard::Post() 等内置 guard 按请求方法匹配;方法构造器内部已带对应方法 guard,显式再挂通常是重复。

概念解释

方法是最常见的路由区分条件。web::get() 生成的路由天然只匹配 GET,无需额外挂方法 guard。显式方法 guard 主要用于通用 web::route() 或自定义组合场景。方法不匹配时路由跳过,最终未命中落到 404/405 行为。

原理流程

  1. 请求进入候选路由。
  2. 方法 guard 对比请求 Method。
  3. 一致则放行,不一致跳过。
  4. 资源内继续尝试其它方法路由。

代码或图示

use actix_web::guard;

web::resource("/items")
    .route(web::route().guard(guard::Post()).to(create))

常见误区

  • 方法构造器上重复挂同方法 guard,配置冗余。
  • 自定义 guard 里忘记校验方法,任意方法都能进入。

追问

  • HEAD 请求如何匹配?答:有对应方法 guard;HEAD 与 GET 的资源处理差异以文档当前版本为准。
  • 方法不匹配返回 405 还是继续匹配?答:actix-web 会在路由表内继续尝试;最终行为(405 或 404)以当前版本文档为准。

04.4.4.1-034 自定义 guard 如何实现,能拿到哪些请求信息?

一句话结论

实现 Guard trait 的判定方法,读取请求方法、路径、头部等上下文返回布尔;自定义 guard 适合固定前缀、特定 Host 等路由级条件。

概念解释

guard 上下文提供请求元数据访问,不包括 body 消费能力。判定逻辑应保持无副作用、快执行;需要鉴权解析、参数提取的逻辑不应塞进 guard。自定义 guard 注册到资源或路由上参与匹配链。

原理流程

  1. 定义结构体实现 Guard。
  2. 判定方法读取上下文头部/路径等。
  3. 返回 true 匹配,false 跳过。
  4. 注册到资源或路由项。

代码或图示

use actix_web::{guard::Guard, guard::GuardContext};

struct ApiHost;

impl Guard for ApiHost {
    fn check(&self, ctx: &GuardContext<'_>) -> bool {
        ctx.head().headers().get("Host").map(|h| h == "api.example.com").unwrap_or(false)
    }
}

常见误区

  • guard 内做远程鉴权调用,路由匹配阶段引入网络延迟。
  • guard 保存请求相关可变状态,破坏无状态匹配模型。

追问

  • guard 能访问 Data 注入状态吗?答:guard 上下文可见性以文档为准;需要共享配置时优先在构造 guard 时捕获克隆句柄。
  • guard 失败能返回自定义错误体吗?答:guard 只返回布尔,错误体由后续默认服务或错误处理生成。

04.4.4.1-035 guard 判定失败后路由如何继续匹配?

一句话结论

guard 失败的路由被跳过,匹配链尝试同资源下一条路由,再尝试下一资源;全部不匹配才落到默认服务(404)。

概念解释

理解继续匹配机制才能解释「为什么带 guard 的接口没有返回预期 405,而是被另一路由接住」。候选顺序由路由表装配顺序与资源优先级决定。设计路由时避免宽模板 + 严 guard 把窄模板挤到后面。

原理流程

  1. 路径初筛生成候选列表。
  2. 依次运行 guard 链。
  3. 失败则回退到下一候选。
  4. 全部失败进入默认服务。

代码或图示

候选资源 A(guard 失败)→ 候选资源 B(guard 通过)→ handler
全部失败 → 默认服务 404

常见误区

  • 以为 guard 失败立即返回 405,实际还会继续匹配其它路由。
  • 宽路径模板排在前面,严格 guard 放过的请求被宽模板接住。

追问

  • 资源间匹配优先级如何确定?答:按路由表装配与模板特征排序;具体规则以 docs.rs 当前版本为准。
  • 如何验证 guard 实际放行情况?答:测试中用不同方法/头部请求,断言命中的 handler 与响应。

04.4.4.1-036 路径模板中的动态段如何声明与提取?

一句话结论

资源路径用 {id} 形式声明动态段,web::Path<T> 提取器按段位置或字段名解析为类型化值。

概念解释

动态段匹配一段非斜杠路径,模板中的占位名与提取器绑定对应。单参数可用标量类型,多参数用元组或结构体。段值是字符串,提取器完成类型转换;转换失败返回 400 类错误。动态段数量与提取器参数必须对齐。

原理流程

  1. 资源模板声明 {id} 等占位段。
  2. 请求路径按段拆分,占位段捕获字符串值。
  3. Path<T> 反序列化为目标类型。
  4. 绑定为 handler 参数。

代码或图示

#[actix_web::get("/users/{org}/{repo}")]
async fn repo(path: web::Path<(String, String)>) -> String {
    format!("{}/{}", path.0, path.1)
}

常见误区

  • 模板占位段数量与 Path 元组长度不一致,提取失败。
  • 期望段内含斜杠却用普通动态段,斜杠分段不匹配。

追问

  • 多参数结构体怎么绑定?答:Path<Struct> 字段名与占位名对应;字段缺失或类型不匹配返回提取错误。
  • 段值编码如何处理?答:路径段按 URL 解码后再解析;编码斜杠的处理以文档为准。

04.4.4.1-037 通配或剩余路径段如何匹配?

一句话结论

需要捕获尾部剩余路径时使用通配段语法,提取器拿到剩余路径字符串;通配段只能放在模板末尾,具体语法以 docs.rs 当前版本为准。

概念解释

静态资源代理、文件下载、嵌套路径转发这类场景需要匹配前缀后的任意剩余段。通配段把多段路径作为一个值捕获,提取器按字符串接收;业务侧再做路径拆分与安全校验。注意目录穿越校验不能省略。

原理流程

  1. 模板末尾声明通配段。
  2. 请求路径前缀匹配后,剩余部分整体捕获。
  3. 提取器解析为路径字符串。
  4. handler 校验后使用。

代码或图示

// 通配段写法待确认:以 docs.rs actix-web 路由语法为准
#[actix_web::get("/files/{tail:.*}")]
async fn files(tail: web::Path<String>) -> String {
    tail.into_inner()
}

常见误区

  • 通配段放在模板中间,路由无法编译或匹配。
  • 直接用剩余路径拼文件系统路径,未校验 .. 穿越。

追问

  • 通配段能限定文件名扩展名吗?答:可在 handler 内按后缀校验;模板层语法支持范围以文档为准。
  • 剩余路径为空时匹配行为是什么?答:取决于通配段是否允许零段;用测试用例验证空路径与多层路径。

04.4.4.1-038 尾部斜杠归一化由什么中间件负责?

一句话结论

NormalizePath 类中间件可统一路径尾部斜杠的匹配行为,避免 /items 与 /items/ 一个命中一个 404;是否默认启用及配置方式以当前版本文档为准。

概念解释

路径尾部斜杠是常见 404 来源:资源模板不带斜杠,请求带斜杠即不匹配。归一化中间件在匹配前规整路径形式。手动处理时要在路由约定上保持一致,不要依赖客户端自己去掉斜杠。

原理流程

  1. 请求路径进入中间件层。
  2. 按策略规整尾部斜杠。
  3. 规整后的路径进入路由表匹配。
  4. 匹配结果照常生成响应。

代码或图示

use actix_web::middleware::NormalizePath;

App::new()
    .wrap(NormalizePath::default())
    .service(web::resource("/items").route(web::get().to(list)))

常见误区

  • 假设框架自动忽略尾斜杠,实际两个形式行为不同。
  • 归一化策略与反向代理重写规则冲突,路径被改写两次。

追问

  • 归一化会影响查询字符串吗?答:只规整路径部分,查询串保持原样。
  • 301 跳转与内部归一化区别是什么?答:内部规整不产生额外跳转;需要浏览器侧改 URL 时才用重定向策略,具体选项以文档为准。

04.4.4.1-039 请求未命中任何路由时 404 是如何产生的?

一句话结论

路由表全部候选未匹配后进入默认服务,默认服务返回 404 响应;自定义默认服务可返回统一错误 JSON。

概念解释

404 产生于匹配阶段结束,而不是 handler 内部。排查时先确认完整路径(含 scope 前缀、尾斜杠)与方法是否在路由表中。API 项目通常覆盖默认服务,让 404 与业务错误格式一致;静态资源 404 可单独处理。

原理流程

  1. 请求路径遍历资源与路由项。
  2. 模板与 guard 均未命中。
  3. 进入默认服务。
  4. 默认服务生成 404 状态与响应体。

代码或图示

请求 /api/missing
  → scope /api 前缀命中,子资源无匹配
    → 默认服务 → 404 JSON

常见误区

  • 把 404 写在每个 handler 里,资源不存在与路由不存在混淆。
  • 忽略 scope 前缀,用子路径去路由表核对。

追问

  • 404 响应能记录路径与方法吗?答:默认服务处理器可读取请求上下文记录;具体可访问字段以文档为准。
  • 如何区分「路由不存在」与「资源记录不存在」?答:后者在 handler/业务层返回 404 业务错误;前者是路由表未命中。

04.4.4.1-040 路径命中但方法不支持时会产生 405 吗?

一句话结论

路径模板命中但方法路由不匹配时,actix-web 继续在路由表内尝试;最终是否返回 405 取决于版本默认行为,不确定处应以 docs.rs 当前版本实测为准。

概念解释

405(Method Not Allowed)表示路径存在但方法不对。不同框架默认行为有差异:有的继续匹配到 404,有的明确返回 405 并带 Allow 头。actix-web 的默认处理需对照当前版本文档与测试断言,不要凭其它框架经验作答。

原理流程

  1. 路径模板命中资源。
  2. 资源内方法路由逐一匹配。
  3. 无方法匹配则跳出尝试下一资源。
  4. 全部结束后按默认行为返回 404 或 405。

代码或图示

// 测试断言:对 /items 发 DELETE 而资源只注册 GET/POST
// 观察状态码与 Allow 头,确认当前版本默认行为

常见误区

  • 把其它框架的 405 默认行为套到 actix-web 上。
  • 需要明确 405 时未自定义处理,客户端拿到 404 难以排错。

追问

  • 如何强制返回 405 并带 Allow 头?答:通过自定义默认服务或错误处理按路径推断允许方法;实现方式以当前版本文档为准。
  • 405 响应需要 body 吗?答:规范允许无 body,body 内容按接口错误风格补充。

04.4.4.1-041 路由表中资源的匹配优先级如何确定?

一句话结论

候选资源按路由表装配顺序与模板特征(静态段优先于动态段)参与匹配;宽模板排在窄模板前可能拦截本应命中的请求。

概念解释

路由设计要避免「宽泛动态段 + 严格 guard」挤压「精确静态段」。排查误命中问题时,列出所有同前缀资源,比较模板静态段数量与装配顺序。静态路径应优先于参数路径命中,具体排序规则以当前版本实现为准。

原理流程

  1. 收集所有资源模板。
  2. 按匹配优先级排序候选。
  3. 候选依次过模板与 guard。
  4. 首个通过的资源处理请求。

代码或图示

风险组合:
/users/{name}(宽模板,先注册)
/users/me(静态窄路径)
若宽模板先匹配,/users/me 可能被 name="me" 接住

常见误区

  • 动态段模板先于静态路径注册,静态路径被吞。
  • 多版本接口共用前缀,路由边界不清互相拦截。

追问

  • 如何确认实际命中了哪条路由?答:测试中分别请求断言响应;日志中间件可记录路径,必要时在 handler 加区分标识。
  • 模板静态段越多优先级越高吗?答:通常静态段更具体的模板优先;精确规则以源码与文档当前版本为准。

04.4.4.1-042 同一路径的多个 HTTP 方法如何组织在一个资源下?

一句话结论

同一资源内链式注册多条方法路由(GET/POST/PUT/DELETE),共享路径模板与资源级 guard,方法区分由各路由完成。

概念解释

REST 资源的 CRUD 对应同一资源路径的不同方法,集中在一个 resource 下维护最清晰。资源级 guard 对所有方法生效;方法级差异(权限、Content-Type)放在路由层。多方法共享的提取器与数据注入在资源作用域内一次配置。

原理流程

  1. 创建路径资源。
  2. 按方法逐条 .route(web::method().to(handler))。
  3. 资源级条件挂在资源上。
  4. 请求按方法落到对应 handler。

代码或图示

web::resource("/items/{id}")
    .route(web::get().to(get))
    .route(web::put().to(update))
    .route(web::delete().to(delete))

常见误区

  • 每个方法新建一个 resource,路径重复且资源级 guard 要配多份。
  • 方法间权限差异未区分,写操作复用读操作校验。

追问

  • 多方法共享同一个 handler 可以吗?答:可以在路由层把多方法指向同一函数,函数内再按方法分支;更常见是拆分 handler。
  • OPTIONS 预检如何挂?答:在资源上注册 options 路由或由 CORS 中间件统一处理。

04.4.4.1-043 路径模板的静态段与动态段如何区分?

一句话结论

模板中字面量为静态段,{name} 形式为动态段;静态段逐字符匹配,动态段捕获一段路径值。

概念解释

模板由若干段组成,段间以斜杠分隔。静态段要求完全一致,动态段接受任意非斜杠内容并交给提取器。混合模板(如 /v1/users/{id})中静态前缀先缩小匹配范围。设计模板时静态段尽量前置,提高匹配确定性。

原理流程

  1. 拆解模板为段序列。
  2. 请求路径逐段对齐。
  3. 静态段精确匹配,动态段捕获值。
  4. 全部段对齐后进入 guard 判定。

代码或图示

// 静态:/v1、/users;动态:{id}
web::resource("/v1/users/{id}")

常见误区

  • 动态段默认匹配斜杠,期望层级路径时用错段类型。
  • 模板拼写与实际请求大小写不一致,路径区分大小写导致不匹配。

追问

  • 模板支持正则约束动态段吗?答:actix-web 模板语法的正则能力以文档为准;复杂格式校验在提取器或 handler 完成。
  • 空段会匹配吗?答:连续斜杠与空段行为由路径规整与模板规则决定,测试用例覆盖边界。

04.4.4.1-044 查询字符串参与路由模板匹配吗?

一句话结论

路由模板只匹配路径部分,查询字符串不参与模板匹配;查询参数由 web::Query<T> 提取器解析。

概念解释

/items?page=2 中路由只认 /items,page=2 是查询参数。路径匹配失败不会因为查询串不同而命中另一资源。查询参数缺失、类型转换失败由 Query 提取器处理,与路由匹配阶段分离。

原理流程

  1. 拆分 URI 为路径与查询串。
  2. 路径进入路由表匹配。
  3. 查询串留存供提取器解析。
  4. handler 通过 Query<T> 取参数。

代码或图示

#[derive(serde::Deserialize)]
struct Page { page: u32, size: u32 }

#[actix_web::get("/items")]
async fn list(q: web::Query<Page>) -> String {
    format!("page {}", q.page)
}

常见误区

  • 在路由模板里写查询参数,模板无法匹配。
  • 把必填查询参数当路径资源区分,路由表设计混乱。

追问

  • 查询参数类型转换失败返回什么?答:Query 提取器拒绝并映射 400 类响应;错误格式可通过配置调整。
  • 查询串重复参数如何解析?答:按提取器目标类型(单值/集合)解析;规则以 serde 与 Query 文档为准。

04.4.4.1-045 资源、scope、App 三层中间件作用域有何区别?

一句话结论

App 级 wrap 覆盖全部路由,scope 级只覆盖该前缀子树,资源级只包裹单路径;层级越靠内作用域越小。

概念解释

中间件作用域决定哪些请求经过该层。日志、安全头这类通用层放 App;模块级鉴权、前缀级 CORS 放 scope;单路径特殊压缩或缓存放资源。挂错层级会导致要么覆盖不足,要么误伤其它接口。

原理流程

  1. 请求先经过 App 级中间件链。
  2. 匹配 scope 后穿过 scope 级链。
  3. 命中资源再穿过资源级链。
  4. 最后进入 handler,响应反向返回。

代码或图示

App::new()
    .wrap(AppLogger)
    .service(
        web::scope("/admin")
            .wrap(AdminAuth)
            .service(web::resource("/panel").wrap(PanelCache).route(web::get().to(panel)))
    )

常见误区

  • 模块鉴权挂 App 层,需要为每个接口写白名单判断。
  • 资源级中间件重复 App 已有能力,执行两次。

追问

  • 子 scope 能继承父 scope 中间件吗?答:请求穿过父链后再进入子链,父级中间件对子树生效;这是包裹继承而非重复挂载。
  • 数据注入层级与中间件层级对应吗?答:同样按 App/scope/资源作用域可见,内层取不到外层未注入的数据。

04.4.4.1-046 资源级 guard 与路由级 guard 如何配合?

一句话结论

资源级 guard 对该路径所有方法生效,路由级 guard 只约束单方法;两者按层级叠加,全部通过才匹配该路由。

概念解释

资源级条件(Host、路径前缀)与路由级条件(Content-Type、方法)分层放置,避免条件散落。请求先过资源 guard,再过路由 guard。设计时先判断条件作用于整个资源还是单个方法,再选挂载层。

原理流程

  1. 路径命中资源。
  2. 运行资源级 guard 链。
  3. 进入方法路由,运行路由级 guard 链。
  4. 全部通过调用 handler。

代码或图示

web::resource("/internal")
    .guard(guard::Host("internal.example.com"))
    .route(web::post().guard(guard::Header("x-token", "secret")).to(internal))

常见误区

  • 把方法级限制挂到资源层,其它方法被一并拦截。
  • 资源与路由 guard 条件矛盾,路由永远无法匹配。

追问

  • guard 条件矛盾怎么排查?答:逐层用测试请求验证,先资源后路由,定位哪一层拒绝。
  • 资源 guard 失败会尝试其它资源吗?答:会,匹配链继续下一候选。

04.4.4.1-047 路由命名与 URL 反向生成在 actix-web 中如何支持?

一句话结论

资源可命名,需要在服务端按路由标识生成 URL 时使用反向路由能力;具体 API 类型与用法以 docs.rs 当前版本为准。

概念解释

反向生成 URL 避免在代码里硬编码路径字符串,路由调整时联动更新。actix-web 提供路由命名与 URL 生成相关类型;项目中若主要做 JSON API,反向路由使用频率不高,但表单页面与重定向场景值得使用。

原理流程

  1. 注册资源时指定路由名称。
  2. 服务端需要链接时按名称与参数生成路径。
  3. 生成结果用于重定向或页面上下文。
  4. 路由改名时编译/测试暴露引用不一致。

代码或图示

// 命名与反向生成 API 待确认:以 docs.rs actix-web 当前版本为准
web::resource("/items/{id}")
    .name("item_detail")
    .route(web::get().to(detail))

常见误区

  • 重定向路径手写拼接,路由调整后漏改。
  • 反向路由参数类型与模板占位段不匹配。

追问

  • 反向生成能产出绝对 URL 吗?答:取决于 API 是否传入请求上下文与主机信息;相对路径生成通常更基础,具体能力以文档为准。
  • 未命名资源能反向生成吗?答:一般需要名称作为索引;未命名只能手写路径。

04.4.4.1-048 未匹配请求进入的默认服务如何定制?

一句话结论

默认服务处理路由表未命中的请求,可替换为统一错误响应;定制点在 App 装配阶段注册默认处理,与具体资源路由分离。

概念解释

默认服务是匹配链的最后一环。定制时要区分 API 前缀与页面路径:API 返回 JSON 错误,页面返回 404 模板。注意默认服务同样受 App 级中间件包裹,访问日志与安全头照常生效。

原理流程

  1. 全部资源与路由未匹配。
  2. 进入默认服务处理器。
  3. 按路径或 Accept 头选择响应格式。
  4. 生成 404/405 类响应写出。

代码或图示

async fn default_handler(req: actix_web::HttpRequest) -> actix_web::HttpResponse {
    actix_web::HttpResponse::NotFound()
        .json(serde_json::json!({ "error": "not_found", "path": req.path() }))
}

常见误区

  • 默认处理器读取 body 后影响后续(默认服务本无后续,但仍不应消费)。
  • 静态资源 404 与 API 404 返回同一格式,前端解析混乱。

追问

  • 默认服务能注册多个吗?答:匹配链只有一个默认落点;多格式分支在处理器内判断。
  • 自定义默认服务后静态资源还能命中吗?答:静态资源需先注册对应资源/代理路由,未注册才落到默认服务。

04.4.4.1-049 路由注册阶段常见编译错误有哪些?

一句话结论

常见错误包括 handler 签名不满足 trait 约束、提取器类型不匹配、资源/路由链式方法返回类型错位、Data 类型未注入;编译器会指出具体函数与约束。

概念解释

actix-web 用复杂泛型约束校验 handler 与路由装配,报错信息有时较长。排查路径:先看 handler 参数与返回类型是否符合提取器/Responder 约束,再看链式调用是否在正确类型上继续,最后核对 Data 注册类型。

原理流程

  1. 编译器检查 handler 是否实现服务 trait。
  2. 校验提取器参数约束与返回 Responder。
  3. 检查装配链方法所属类型。
  4. 定位首个不满足的约束并修正。

代码或图示

常见报错方向:
handler 签名不匹配 → 检查参数提取器与返回类型
链式方法找不到 → 确认当前是 Resource 还是 Route 类型
Data 提取不到 → 核对 app_data 注册类型

常见误区

  • 看到长泛型报错就改返回类型,未定位具体不满足的 trait。
  • 在 Resource 上调用 Route 层方法,或反之。

追问

  • 闭包 handler 与函数 handler 约束一致吗?答:都需满足 handler trait;捕获变量的所有权与 Send 约束按异步规则检查。
  • 如何简化报错定位?答:先把 handler 拆成独立函数,确认签名编译通过后再接路由链。

04.4.4.1-050 路由排错的方法论是什么?

一句话结论

按「完整路径 → 方法 → 模板段 → guard → 数据/提取器」逐层核对:先拼出 scope 前缀后的完整路径,再确认方法与模板匹配,然后检查 guard 拒绝条件,最后看提取器与 Data 注入。

概念解释

接口不通时不要直接怀疑 handler 业务。分层定位:404 查路径与模板,方法不对查路由 guard,进入后参数错查提取器,响应错查 Responder 与中间件。测试用最小请求分别覆盖正常与边界条件,日志记录命中路径。

原理流程

  1. 记录实际请求方法与完整 URI。
  2. 对照 scope 前缀拼出模板路径。
  3. 检查资源/路由方法与 guard 条件。
  4. 命中后核对提取器类型与 Data 注册;最后检查响应层。

代码或图示

排错清单:
路径是否含 scope 前缀、尾斜杠
方法是否注册为对应路由
guard 是否拒绝(Host/Header/方法)
Path/Query/Json 类型是否匹配
Data 类型是否一致
Responder 与中间件是否改写响应

常见误区

  • 跳过路由层直接读 handler 代码,问题根本不在业务。
  • 只在浏览器手测,缺少不同方法与边界路径的自动化断言。

追问

  • 如何快速确认请求命中了哪个 handler?答:测试中调用对应路由断言响应;临时在 handler 加标识日志,确认后移除。
  • 路由问题需要看运行时状态吗?答:路由表在装配期定型,排错以注册代码与测试请求为主,不依赖运行期动态修改。

04.4.4.1-051 actix-web 提取器基于哪个 trait,整体机制是什么?

一句话结论

提取器实现 FromRequest trait,在匹配路由后从请求与 payload 中构造类型化参数;失败时返回实现 ResponseError 的错误,由服务映射为 HTTP 响应。

概念解释

提取器是 actix-web 把原始 HTTP 请求转成 handler 强类型参数的抽象。trait 定义异步构造方法,可访问请求头、路径、查询串与 body 流。每个 handler 参数对应一个提取器实现,框架按参数位置依次构造,任一失败即短路。

原理流程

  1. 路由匹配成功,拿到 HttpRequest 与 Payload。
  2. 按参数列表调用各提取器的 from_request。
  3. 提取器解析并校验数据,成功返回类型值。
  4. 失败返回错误类型,映射为错误响应。

代码或图示

// 提取器 trait 签名示意,具体关联类型与方法以 docs.rs 当前版本为准
// trait FromRequest: Sized {
//     type Error: ResponseError;
//     async fn from_request(req: &HttpRequest, payload: &mut Payload) -> Result<Self, Self::Error>;
// }

常见误区

  • 以为提取器在路由匹配之前运行;实际是匹配成功后才构造参数。
  • 多个提取器各自消费 body,第二个拿到空流。

追问

  • 提取器与 guard 怎么分工?答:guard 做路由级布尔判定,不产出参数;提取器在匹配后构造类型化值并处理拒绝。
  • 提取器可以访问注入的 Data 吗?答:可以从请求扩展或数据表中读取共享状态;具体访问方式按当前版本 API。

04.4.4.1-052 web::Path<T> 如何解析路径参数?

一句话结论

Path<T> 从路径动态段取值并反序列化为 T,支持标量、元组与结构体;段值类型转换失败返回 400 类提取错误。

概念解释

路径段在路由模板中声明,提取器按位置或字段名绑定。标量直接解析,元组按段顺序,结构体按占位名匹配。Path 不碰 body,可与 body 提取器并列使用。路径参数是字符串,数值、枚举等类型在提取阶段完成转换。

原理流程

  1. 路由模板捕获各动态段字符串。
  2. Path 提取器按 T 的形式绑定。
  3. 反序列化/类型转换完成。
  4. 成功传入 handler,失败返回提取错误。

代码或图示

#[actix_web::get("/items/{id}")]
async fn item(id: web::Path<u64>) -> String {
    id.into_inner().to_string()
}

常见误区

  • 段数与元组长度不一致,提取失败。
  • 路径段含非数字内容却用 u64 接收,转换错误被当成 400。

追问

  • Path 取值方法有哪些?答:into_inner 解包内部值;元组用 .0/.1,结构体访问字段,具体方法以文档为准。
  • 路径参数需要 Deserialize 吗?答:结构体/元组绑定依赖 serde 反序列化;标量按目标类型解析。

04.4.4.1-053 Path 元组绑定与结构体绑定如何选择?

一句话结论

段少且顺序固定用元组 Path<(A, B)>,段多或语义明确用结构体 Path<Struct> 按字段名绑定;两种方式都要求与模板占位对齐。

概念解释

元组按位置绑定,模板调整段顺序时代码要同步改;结构体按名字绑定,重排模板段不影响字段对应。项目中段数超过两个或模板可能演进时,结构体可读性与可维护性更好。结构体需 derive Deserialize。

原理流程

  1. 模板声明占位段名。
  2. 元组按位置收集段值。
  3. 结构体按字段名匹配段值。
  4. 绑定结果作为 handler 参数。

代码或图示

#[derive(serde::Deserialize)]
struct Repo { org: String, name: String }

#[actix_web::get("/repos/{org}/{name}")]
fn repo(path: web::Path<Repo>) -> String {
    format!("{}/{}", path.org, path.name)
}

常见误区

  • 结构体字段名与模板占位名不一致,反序列化失败。
  • 元组顺序与模板段顺序写反,值错位但编译通过。

追问

  • 结构体能接收部分段吗?答:未声明的段不绑定;模板段与结构体字段应完整对齐,缺失行为以文档为准。
  • Path 结构体需要 Clone 吗?答:提取器按请求构造,一般不要求 Clone;具体 bound 以 trait 文档为准。

04.4.4.1-054 web::Query<T> 如何解析查询参数?

一句话结论

Query<T> 从 URI 查询串反序列化出 T,T 需实现 Deserialize;字段缺失、类型不符或编码错误会被提取器拒绝。

概念解释

查询串是 URL 后的键值对集合,Query 用 serde 风格结构解析。分页、过滤、排序参数常用 Query 接收。查询参数可空字段用 Option<T>,必填字段缺失即拒绝。Query 不消费 body,可与 body 提取器共存。

原理流程

  1. 从 URI 取出查询串。
  2. 解析为键值对映射。
  3. 反序列化为目标结构体。
  4. 成功传入 handler,失败返回 Query 错误。

代码或图示

#[derive(serde::Deserialize)]
struct Filter { keyword: Option<String>, page: u32 }

#[actix_web::get("/search")]
async fn search(q: web::Query<Filter>) -> String {
    format!("page {}", q.page)
}

常见误区

  • 必填查询字段未用 Option,缺参直接拒绝。
  • 把 body 提交的数据塞进查询串,暴露在日志与历史记录中。

追问

  • 重复查询参数如何解析?答:目标类型用集合接收;单值类型取首值还是报错以 Query 文档为准。
  • Query 解析失败默认状态码是什么?答:通常映射 400;可通过 QueryConfig 定制错误响应。

04.4.4.1-055 QueryConfig 能定制哪些解析错误行为?

一句话结论

QueryConfig 可配置 Query 提取器的错误处理器与限制,把解析失败映射为自定义状态码与错误体;通过 app_data 注入生效。

概念解释

不同接口可能希望 Query 错误返回统一 JSON 错误格式,而不是框架默认文本。配置项包括错误处理回调、payload/字段限制等(按当前版本支持项)。配置以类型注册到 App 数据表,Query 提取器按类型查找。

原理流程

  1. 构造 QueryConfig 并设置错误处理器。
  2. app_data 注入配置。
  3. Query 提取器解析失败时调用配置处理器。
  4. 生成定制错误响应。

代码或图示

App::new()
    .app_data(web::QueryConfig::default().error_handler(|err, _req| {
        actix_web::error::BadRequest(err).into()
    }))
    .service(web::resource("/items").route(web::get().to(list)))

常见误区

  • 配置注册类型与提取器查找类型不一致,配置不生效。
  • 错误处理器返回内部错误细节,泄露给客户端。

追问

  • Json/Form/Payload 有类似配置吗?答:有对应 JsonConfig、FormConfig、PayloadConfig,配置项按各提取器文档。
  • 错误处理器接收什么上下文?答:解析错误与请求引用;可按请求路径定制错误格式,具体签名以文档为准。

04.4.4.1-056 web::Json<T> 提取器如何解析请求体?

一句话结论

Json<T> 从 body 读取 JSON 并反序列化为 T: Deserialize,校验 Content-Type 与大小限制;解析失败返回 400/415 类错误响应。

概念解释

Json 是 body 提取器,消费整个请求流。handler 中 Json 参数通常放在最后;结构体字段、类型与请求 JSON 对齐。反序列化错误(缺字段、类型错、格式坏)由提取器包装为 Web 错误。响应侧的 web::Json 则做序列化,约束方向相反。

原理流程

  1. 检查请求 Content-Type 与配置匹配。
  2. 按限制读取 body 字节。
  3. serde 反序列化为 T。
  4. 成功传入 handler,失败进入错误处理器。

代码或图示

#[derive(serde::Deserialize)]
struct CreateItem { name: String, count: u32 }

#[actix_web::post("/items")]
async fn create(item: web::Json<CreateItem>) -> actix_web::HttpResponse {
    actix_web::HttpResponse::Created().json(item.into_inner())
}

常见误区

  • 同一 handler 放两个 body 提取器,后者读到空 body。
  • 请求未带 JSON Content-Type 被拒绝,前端调试时漏设头。

追问

  • Json 提取器限制 body 大小在哪配?答:JsonConfig::limit(...);默认值与单位以 docs.rs 当前版本为准。
  • 响应 Json 与请求 Json 类型约束区别?答:请求要 Deserialize,响应包装要 Serialize;同一 DTO 常同时 derive 两者。

04.4.4.1-057 JsonConfig 的内容类型校验与错误处理如何配置?

一句话结论

JsonConfig 可配置 body 大小上限、Content-Type 匹配规则与错误处理器;不匹配或超限按配置映射为错误响应。

概念解释

Content-Type 校验避免把表单或纯文本 body 当 JSON 解析。错误处理器可把 serde 错误转成统一错误 JSON。大小限制防止大 body 撑爆内存;超限与解析失败应区分状态码语义。配置注入方式与 QueryConfig 一致。

原理流程

  1. 构造 JsonConfig 设置 limit 与错误处理器。
  2. App 层 app_data 注入。
  3. Json 提取器按配置校验类型与大小。
  4. 失败调用错误处理器生成响应。

代码或图示

App::new()
    .app_data(
        web::JsonConfig::default()
            .limit(4096)
            .error_handler(|err, _req| actix_web::error::BadRequest(err).into())
    )
    .service(web::resource("/items").route(web::post().to(create)))

常见误区

  • 只配错误处理器,忘记设 limit,大 body 占用内存。
  • 把反序列化错误统一映射 500,实际应是 400 客户端错误。

追问

  • Content-Type 不匹配返回什么状态?答:通常 415 或 400,具体默认行为以当前版本文档为准。
  • 全局 Json 配置能按接口差异化吗?答:配置按类型注入,差异化可在 handler 内二次校验或拆分提取器。

04.4.4.1-058 web::Form<T> 提取器如何处理表单编码 body?

一句话结论

Form<T> 解析 application/x-www-form-urlencoded 表单 body 为 T: Deserialize;与 Json 同为 body 提取器,同一 handler 不能并存。

概念解释

传统表单提交用 URL 编码键值对,Form 提取器按字段名绑定结构体。文件上传在 actix-web 生态中通常配合 multipart 提取器或 lab 扩展;具体 multipart 支持以当前版本与配套 crate 文档为准。Form 解析失败走 FormConfig 错误处理。

原理流程

  1. 检查 body 编码类型。
  2. 读取并解析 URL 编码键值对。
  3. 反序列化为结构体。
  4. 成功传入 handler,失败返回表单错误。

代码或图示

#[derive(serde::Deserialize)]
struct Login { username: String, password: String }

#[actix_web::post("/login")]
async fn login(form: web::Form<Login>) -> String {
    format!("hello {}", form.username)
}

常见误区

  • 前端提交 JSON 却用 Form 接收,解析失败。
  • 表单字段名与结构体字段不一致,绑定为空或报错。

追问

  • Form 与 Query 解析规则一样吗?答:都是键值反序列化,但 Form 来源是 body,Query 来源是查询串;编码细节各有实现。
  • multipart 表单在 actix-web 怎么接?答:查 actix-web 当前版本内置能力与 actix-web-lab 等配套扩展;不确定处标注待确认并核对 docs.rs。

04.4.4.1-059 web::Data<T> 提取器如何取出共享状态?

一句话结论

Data<T> 从 App 注入的数据表按类型取出共享句柄,对应注册时的 web::Data::new(value);类型必须完全一致。

概念解释

Data 是跨请求共享状态的提取器:配置、连接池、缓存句柄都经此注入。它不消费 body,可与任何 body 提取器并列。注册与提取类型不匹配时取不到值,编译或运行期暴露。Data 内部共享,内部可变需同步原语保护。

原理流程

  1. 启动装配时 app_data(Data::new(value))。
  2. handler 参数声明 Data<T>。
  3. 提取器按类型查数据表。
  4. 返回共享句柄供业务使用。

代码或图示

struct AppConfig { title: String }

async fn handler(cfg: web::Data<AppConfig>) -> String {
    cfg.title.clone()
}

App::new()
    .app_data(web::Data::new(AppConfig { title: "ann".into() }))
    .service(web::resource("/").route(web::get().to(handler)))

常见误区

  • 注册 Data<Config>,提取写成 Data<Arc<Config>>,类型不匹配。
  • 在 Data 里放请求级数据,并发下串号。

追问

  • Data 提取器与 State 类提取器概念对应吗?答:actix-web 中共享状态入口就是 Data;其它框架的 State 概念在此由 Data 承担。
  • Data 内字段能直接改吗?答:共享引用下需内部用 Mutex/RwLock/原子保护,不能直接可变借用。

04.4.4.1-060 web::Bytes 提取器如何接收原始 body 字节?

一句话结论

Bytes 把整个 body 读取为不可变字节缓冲,适合二进制协议、原始文本等无结构 body;它也是 body 提取器,只能在 handler 中出现一次。

概念解释

web::Bytes 是 bytes crate 字节类型的 re-export,零拷贝共享切片。需要自行解析 body 格式( protobuf、自定义二进制)时用它。读取大小受 Payload 配置限制;超大 body 应改用流式 Payload 分批处理。

原理流程

  1. 提取器从 Payload 读取完整 body。
  2. 聚合为 Bytes 缓冲。
  3. 作为 handler 参数传入。
  4. 业务按协议解析字节。

代码或图示

#[actix_web::post("/raw")]
async fn raw(body: web::Bytes) -> actix_web::HttpResponse {
    actix_web::HttpResponse::Ok().body(format!("{} bytes", body.len()))
}

常见误区

  • 用 Bytes 接 JSON 后再手动反序列化,绕过 Json 提取器的类型校验与配置。
  • 大文件整体读入 Bytes,内存随文件大小增长。

追问

  • Bytes 与 Vec 有什么区别?答:Bytes 引用计数共享切片,克隆廉价;Vec 持有独占缓冲。
  • body 超限在哪里配置?答:PayloadConfig::limit(...);默认值以文档为准。

04.4.4.1-061 web::Payload 与 Bytes 提取器如何选择?

一句话结论

Payload 是原始 body 流,适合分批流式处理;Bytes 是完整缓冲,适合一次性解析的 body。需要背压与大文件处理时选 Payload。

概念解释

Payload 提供异步流接口,handler 可循环读取 chunk 写入下游(文件、压缩、转发)。Bytes 在提取器阶段就把流读完,失去流式优势。两者都是 body 提取器,按 body 大小与处理方式取舍。

原理流程

  1. handler 参数接收 Payload 流。
  2. 循环从流中拉取 chunk。
  3. 边读边处理或落盘。
  4. 流结束后生成响应。

代码或图示

use actix_web::web::Payload;

#[actix_web::post("/stream")]
async fn stream(mut payload: Payload) -> actix_web::Result<actix_web::HttpResponse> {
    while let Some(chunk) = payload.next().await {
        let _chunk = chunk?;
        // 分批处理 chunk
    }
    Ok(HttpResponse::Ok().finish())
}

常见误区

  • 先拿 Payload 读完再传给 Bytes 提取器,重复消费流。
  • 流式处理中做阻塞磁盘写入,卡住异步调度。

追问

  • Payload chunk 类型是什么?答:字节 chunk 的异步流项;具体错误类型以 FromRequest 文档为准。
  • 流式上传如何限制总大小?答:在读取循环中累计字节数并配合 PayloadConfig 上限,超限提前中断。

04.4.4.1-062 web::Header 提取器如何读取指定请求头?

一句话结论

web::Header<T> 按类型化头提取器读取请求头,内置实现解析常见标准头;原始头也可通过 HttpRequest::headers() 直接遍历。

概念解释

类型化头提取器把头部字符串解析为结构化类型(如 Content-Type、Host)。未覆盖的自定义头用请求对象直接取 headers().get(...)。头缺失或解析失败按提取器错误处理。Header 提取不消费 body。

原理流程

  1. 框架按 Header 类型定位对应头名。
  2. 读取头部字符串并解析。
  3. 成功得到结构化头值。
  4. 失败返回提取错误。

代码或图示

#[actix_web::get("/")]
async fn with_header(req: actix_web::HttpRequest) -> String {
    match req.headers().get("X-Trace-Id") {
        Some(v) => v.to_str().unwrap_or_default().to_string(),
        None => "none".into(),
    }
}

常见误区

  • 自定义头也强行套内置 Header 类型,解析失败。
  • 头值含非 ASCII 字符未按编码处理,to_str 出错。

追问

  • 内置有哪些类型化 Header?答:按 http 头类型枚举提供;完整清单以 docs.rs 当前版本为准。
  • 多值头如何取?答:直接访问 headers 迭代同名头;类型化提取器通常取首值。

04.4.4.1-063 handler 参数顺序有什么约束,body 为什么只能消费一次?

一句话结论

不碰 body 的提取器可在前,body 提取器通常放在参数列表最后;body 流一次性消费,多个 body 提取器会让后者读到空流。

概念解释

Payload 是异步流,读取后无法回放。Path/Query/Data/Header 这类只读元数据的提取器互不影响;Json/Form/Bytes/Payload 之间互斥。框架对参数元组数量有上限,具体上限以当前版本文档为准。

原理流程

  1. 框架按参数位置依次构造提取器。
  2. 元数据提取器读取请求上下文。
  3. body 提取器消费 Payload 流。
  4. 后续 body 提取器拿到空流或报错。

代码或图示

// 正确:Path 在前,Json body 在后
#[actix_web::post("/items/{id}")]
async fn update(id: web::Path<u64>, body: web::Json<Update>) -> String {
    format!("{id}")
}

常见误区

  • 把 Json 放参数中间,后面再取 Query(Query 不受影响,但 body 顺序约定被打乱)。
  • 两个 body 提取器并存,测试时偶发解析失败。

追问

  • 提取器构造失败会继续构造后续参数吗?答:失败即短路,后续参数不再构造。
  • 参数超过框架上限怎么拆?答:用结构体聚合相关参数,handler 内字段访问;具体元组上限以文档为准。

04.4.4.1-064 提取器拒绝请求时错误如何映射为 HTTP 状态?

一句话结论

提取器错误类型实现 ResponseError,error_response 生成对应状态码与 body;框架把提取器 Error 包装进 actix_web::Error 后走错误响应链。

概念解释

解析失败不等于 panic:提取器返回结构化错误,错误类型声明响应映射。常见映射:JSON 格式坏 → 400,Content-Type 不符 → 415,body 超限 → 413/400。自定义错误类型可复用这套映射,统一错误格式。

原理流程

  1. 提取器构造失败返回 Self::Error。
  2. 错误类型经 Error::from 包装。
  3. 服务调用 error_response 生成 HttpResponse。
  4. 响应经中间件链写出。

代码或图示

impl actix_web::ResponseError for ExtractError {
    fn error_response(&self) -> actix_web::HttpResponse {
        actix_web::HttpResponse::BadRequest().json(serde_json::json!({ "error": self.to_string() }))
    }
}

常见误区

  • 提取器内 unwrap 解析结果,panic 代替结构化错误。
  • 客户端错误被映射成 500,监控误报服务端故障。

追问

  • 提取器错误能被全局错误处理器接管吗?答:错误经 ResponseError 生成响应;全局错误加工在中间件/默认服务层,具体挂钩点以文档为准。
  • 413 与 400 如何区分?答:载荷过大倾向 413,格式/类型错误倾向 400;框架默认映射需实测核对。

04.4.4.1-065 自定义提取器实现要点有哪些?

一句话结论

实现 FromRequest trait:定义错误类型并实现 ResponseError,在异步构造方法中读取请求/流并返回类型化值;只读元数据优先于消费 body。

概念解释

需要把认证头、自定义签名、聚合参数封装成强类型时写自定义提取器。构造方法是异步的,访问 Payload 要注意消费边界;错误类型要给出合理状态码。提取器内部可读取注入的 Data 作为配置或依赖。

原理流程

  1. 定义提取器结构体与错误枚举。
  2. 错误枚举实现 ResponseError。
  3. 实现 from_request 完成解析与校验。
  4. handler 直接声明该类型作为参数。

代码或图示

struct AuthUser { id: String }

// impl FromRequest for AuthUser {
//     type Error = AuthError;
//     async fn from_request(req: &HttpRequest, _payload: &mut Payload) -> Result<Self, Self::Error> {
//         let token = req.headers().get("Authorization")
//             .and_then(|v| v.to_str().ok()).ok_or(AuthError::Missing)?;
//         Ok(AuthUser { id: token.to_string() })
//     }
// }

常见误区

  • 自定义提取器读取 body 后未考虑后续提取器需求。
  • 错误类型只实现 std Error,未实现 ResponseError,无法生成响应。

追问

  • 自定义提取器能访问 Data 吗?答:可从请求扩展表或上下文读取注入值;具体途径以当前版本 API 为准。
  • 提取器内可以做远程校验吗?答:技术上可以,但路由阶段引入远程调用会放大延迟;鉴权建议控制调用范围与超时。

04.4.4.1-066 actix_web::Error 与提取器错误类型是什么关系?

一句话结论

Error 是 Web 层通用错误包装,任何实现 ResponseError 的类型都可 Into 包装;handler 返回 Result<impl Responder, Error> 统一错误出口。

概念解释

业务错误、提取器错误、IO 错误在 handler 汇合为 Error。Error::from 保留来源类型,错误响应由来源的 ResponseError 实现决定。包装后错误链仍可通过 source 追溯原始错误。不要把所有错误笼统 Error::from(anyhow) 丢失类型映射。

原理流程

  1. 业务返回自定义错误或标准错误。
  2. ? 经 From 包装为 actix_web::Error。
  3. 服务调用错误的 error_response。
  4. 生成 HTTP 响应写出。

代码或图示

async fn handler() -> actix_web::Result<actix_web::HttpResponse> {
    let v = may_fail()?; // 错误类型 Into<actix_web::Error>
    Ok(actix_web::HttpResponse::Ok().body(v))
}

常见误区

  • 用 anyhow::Error 作为 handler 错误类型,丢失状态码映射。
  • 错误包装后打印完整内部链路到对外响应。

追问

  • ResponseError 与 std Error 都要实现吗?答:通常借助 thiserror 实现 std 错误链,再单独实现 ResponseError 提供响应映射。
  • 错误链如何追溯?答:Error 保留 source,日志侧沿链记录;对外响应只暴露安全信息。

04.4.4.1-067 handler 支持多少个提取器参数?

一句话结论

框架通过元组实现为有限数量的提取器组合提供支持,具体上限以 docs.rs 当前版本为准;参数过多时应聚合为结构体,而不是堆到元组上限。

概念解释

actix-web 为不同长度的参数元组实现 handler trait,超出上限编译报错。工程上常见做法:路径/查询/数据分别用结构体包装,handler 参数保持少量。不要为了凑上限把所有 DTO 平铺成参数。

原理流程

  1. 编译器检查 handler 参数元组是否在支持列表。
  2. 各参数按提取器约束构造。
  3. 超出上限报 trait 未实现错误。
  4. 重构为结构体聚合参数。

代码或图示

// 聚合示例:查询参数独立结构体,路径与 Data 分开
async fn handler(
    path: web::Path<Id>,
    query: web::Query<Filter>,
    data: web::Data<AppState>,
) -> String { "ok".into() }

常见误区

  • 接口参数十几个平铺,逼近元组上限且可读性差。
  • 报错后盲目拆分 handler,未用结构体聚合。

追问

  • 元组上限版本间会变吗?答:可能随版本调整,作答时标注以当前版本文档为准。
  • 结构体参数会受元组上限约束吗?答:结构体本身是单个提取器参数,内部字段数量不占元组名额。

04.4.4.1-068 提取器构造过程中的异步与阻塞边界是什么?

一句话结论

提取器构造是异步流程,可 .await 读取流;同步阻塞 IO 与 CPU 密集计算不应占用异步调度线程,需移到阻塞任务隔离。

概念解释

认证解析、body 读取都是异步等待点。提取器内若做同步磁盘读取、加锁长等待,会卡住 worker。自定义提取器编写时要区分异步等待与阻塞计算;阻塞结果通过任务句柄 await 取回。

原理流程

  1. 提取器 from_request 异步执行。
  2. 异步读取头与 body 流。
  3. 阻塞操作移交阻塞任务。
  4. 聚合结果返回 handler 参数。

代码或图示

// 阻塞计算在 spawn_blocking 内完成,再 await 句柄
async fn heavy() -> actix_web::Result<Vec<u8>> {
    let h = actix_web::rt::task::spawn_blocking(|| vec![1u8, 2, 3]).await?;
    Ok(h)
}

常见误区

  • 提取器内同步调用阻塞数据库驱动,卡住整个 worker。
  • 阻塞任务返回非 Send 类型,跨线程编译失败。

追问

  • 提取器错误能否包含阻塞任务 Join 错误?答:可以包装进自定义错误类型,映射为 500 或 422 类响应。
  • 如何监控提取器阻塞?答:访问日志看耗时分布,慢提取器单独打点排查。

04.4.4.1-069 直接用 HttpRequest 能访问哪些请求信息?

一句话结论

HttpRequest 提供方法、路径、查询串、头部、连接信息与请求扩展等只读访问;需要类型化参数时仍用提取器。

概念解释

handler 可直接声明 HttpRequest 作为参数,读取原始请求上下文。它不消费 body,适合日志、追踪、头透传等场景。类型化提取器是在它之上的结构化封装;直接访问常用于提取器未覆盖的自定义头与路径。

原理流程

  1. handler 参数接收 HttpRequest 引用。
  2. 通过方法读取 path、query、headers。
  3. 必要时读取请求扩展表中的注入数据。
  4. 业务基于原始上下文处理。

代码或图示

#[actix_web::get("/")]
async fn index(req: actix_web::HttpRequest) -> String {
    format!("{} {} query={:?}", req.method(), req.path(), req.query_string())
}

常见误区

  • 用 HttpRequest 手动解析 JSON body,重复实现提取器逻辑。
  • 保留 HttpRequest 引用跨越 .await 持有不当生命周期,编译报错。

追问

  • HttpRequest 能修改请求吗?答:它是请求上下文只读视图;加工请求的逻辑放在中间件或守卫层。
  • 请求扩展表存什么?答:中间件/提取器间传递的请求级数据;具体 API 以文档为准。

04.4.4.1-070 提取器与 guard、中间件的职责边界如何再梳理?

一句话结论

guard 做路由级布尔判定,中间件做跨切面包裹,提取器在匹配后构造类型化参数;三层依次作用,不要互相替代。

概念解释

边界清晰才能避免逻辑乱放:是否归当前路由 → guard;日志/鉴权/头加工 → 中间件;业务参数取值与校验 → 提取器/handler。鉴权可在中间件做存在性校验,身份类型化提取放提取器;细粒度权限在 handler 判断。

原理流程

  1. 请求穿过 App/scope 中间件链。
  2. 路由模板与 guard 判定归属。
  3. 提取器构造类型化参数。
  4. handler 执行业务,响应反向穿过中间件。

代码或图示

中间件:日志、CORS、全局鉴权钩子
guard:方法/Host/Header 路由条件
提取器:Path/Query/Json/Data/Header 类型化参数
handler:业务规则与资源权限

常见误区

  • 把参数校验写进 guard,丢失结构化错误返回能力。
  • 把全局横切逻辑塞进每个 handler 重复实现。

追问

  • 鉴权落在哪层最合适?答:全局存在性校验放中间件,Claims 类型化放提取器,资源归属权限放 handler。
  • 三层都能读头吗?答:都能读,但产出与职责不同;重复读取应避免。

04.4.4.1-071 为什么同一 handler 不能同时接收 Form 与 Json?

一句话结论

两者都消费整个 body 流,body 只能读一次;同时声明会导致其中一个解析为空或失败。混合数据应拆分接口或用 multipart/统一编码。

概念解释

请求 body 是一次性异步流,提取器读取后不可回放。Form 与 Json 都是 body 提取器,并列声明在 actix-web 的提取模型下不成立。实际场景:表单字段与文件走 multipart,结构化数据用 JSON;不要在一个接口里混用两种编码。

原理流程

  1. handler 参数声明 body 提取器 A。
  2. A 消费 Payload 流。
  3. 提取器 B 再读流,得到空数据。
  4. B 解析失败,请求被拒绝。

代码或图示

// 错误示范:两个 body 提取器
// async fn bad(form: web::Form<F>, json: web::Json<J>) { }

// 正确:按编码二选一,或 multipart 统一接收

常见误区

  • 测试只发了其中一种编码,偶发通过后误以为没问题。
  • 前端混合提交,后端接口契约不清。

追问

  • 需要表单字段加文件上传怎么办?答:用 multipart 表单统一承载,按当前版本提取能力或配套 crate 解析。
  • body 可以预读缓存复用吗?答:框架默认不缓存 body;如需预检后复用,要在提取器层自行缓冲并交还,注意内存限制。

04.4.4.1-072 body 读取大小限制如何配置与排查?

一句话结论

PayloadConfig 及各 body 提取器配置提供 body 大小上限,超限在读取阶段中断;排查超限错误时对照配置上限、实际 body 与错误状态码。

概念解释

大小限制保护内存不被大请求耗尽。不同提取器(Json/Form/Bytes/Payload)有对应配置项,默认值按版本实现。超限表现为读取中断并返回错误,handler 不会拿到完整 body。上传大文件应走流式分批,而不是提高上限后整体缓冲。

原理流程

  1. 装配期注入 Payload/Json/Form 配置。
  2. 提取器读取 body 时累计字节。
  3. 超过上限中断读取。
  4. 错误处理器映射状态码与响应。

代码或图示

App::new()
    .app_data(web::PayloadConfig::default().limit(1 << 20))
    .service(web::resource("/items").route(web::post().to(create)))

常见误区

  • 只调大 Json 限制,Payload 层默认限制仍卡住。
  • 超限错误被当成业务校验失败,未定位到 body 上限。

追问

  • 限制单位是什么?答:字节数,常用位移表达式表示 KiB/MiB;具体默认值以文档为准。
  • 不同接口能设不同上限吗?答:配置按类型注入,差异化可在 handler/自定义提取器内二次累计校验。

04.4.4.1-073 提取器相关测试应覆盖哪些断言?

一句话结论

测试覆盖正常解析、缺失字段、类型错误、编码不符、body 超限与 Data 注入缺失等场景,断言状态码与错误体,而不是只看 handler 是否执行。

概念解释

提取器失败在进入 handler 之前,测试要直接构造对应请求验证拒绝行为。正常用例断言类型化参数正确到达;异常用例断言错误状态与格式。自定义提取器单独构造请求上下文测试,再接入集成测试。

原理流程

  1. 用 TestRequest 构造不同编码与 body 的请求。
  2. call_service 调用测试服务。
  3. 断言状态码、Content-Type 与错误体字段。
  4. 校验 Data 注入与缺失两类分支。

代码或图示

let req = test::TestRequest::post()
    .uri("/items")
    .set_json(&serde_json::json!({ "name": "x" }))
    .to_request();
let resp = test::call_service(&app, req).await;
assert_eq!(resp.status(), actix_web::http::StatusCode::CREATED);

常见误区

  • 只测 happy path,解析失败分支无覆盖。
  • 断言日志文本而非响应状态与 body。

追问

  • 如何测试提取器错误映射?答:构造畸形 body/错误编码请求,断言 error_response 对应的状态码与 JSON 结构。
  • Data 缺失场景怎么测?答:构造不注入该 Data 的测试服务,请求对应 handler 观察提取失败行为。

04.4.4.1-074 提取器阶段常见编译与运行错误有哪些?

一句话结论

编译期:缺 Deserialize/Serialize bound、参数类型不满足 FromRequest、Data 类型不匹配;运行期:解析失败、编码不符、body 超限与注入数据缺失。

概念解释

按错误来源分层定位:编译器指出 trait bound 缺失时先补 derive 或约束;运行期 400/415/413 类响应回到提取器配置与请求构造。自定义提取器还要检查错误类型是否实现 ResponseError。

原理流程

  1. 编译报错沿 handler 签名向上追溯提取器 bound。
  2. 运行错误对照状态码分类解析/编码/超限。
  3. 核对 Data 注册类型与提取类型。
  4. 修正后用测试用例回归。

代码或图示

编译:Deserialize 未 derive / FromRequest 未实现 / Data 类型不一致
运行:400 格式错误 · 415 编码不符 · 413 超限 · 404 路由未命中

常见误区

  • 把运行期提取错误当成 handler 业务 bug,反复读业务代码。
  • 报错信息长就改返回类型,未定位具体缺失的 trait。

追问

  • 提取器 panic 会表现为什么?答:连接层错误或 500;应在提取器内把可预期失败转为结构化错误。
  • 如何快速区分路由问题与提取器问题?答:404 查路由,400/415 查提取器;先看状态码再分层。

04.4.4.1-075 提取器层排错的方法论是什么?

一句话结论

按「请求编码 → body 读取 → 类型反序列化 → 注入数据 → 错误映射」顺序核对:先确认 Content-Type 与 body 完整到达,再查字段类型与配置,最后看 Data 与错误响应格式。

概念解释

提取器问题大多是契约不一致:前端字段名/类型与 DTO 不符、编码头漏设、Data 类型写错。排错先抓原始请求(方法、路径、头、body 原文),再对照提取器配置与结构体定义。测试用最小复现请求定位到具体提取器。

原理流程

  1. 记录请求头与原始 body。
  2. 确认 body 未被前序提取器消费。
  3. 核对 DTO 字段名、类型与可空性。
  4. 检查 Json/Payload 配置与 Data 注入类型,验证错误映射。

代码或图示

排错清单:
Content-Type 是否与提取器匹配
body 是否完整读取(未超限)
字段名/类型/Option 可空性
Data 注册类型与提取类型一致
错误状态码与错误体格式

常见误区

  • 只看后端 DTO,不核对前端实际发送的 body 原文。
  • 提取器失败后在 handler 里兜底处理,掩盖契约问题。

追问

  • 如何打印提取期收到的原始 body?答:在中间件或调试提取器中记录(注意脱敏),不要在生产长期开启。
  • 提取器契约文档怎么维护?答:DTO 字段与校验规则写进接口契约,前后端按契约对齐。

04.4.4.1-076 app_data 与历史 data 方法在数据注入上有什么区别?

一句话结论

app_data 直接把值插入应用数据表,data 是包装为 web::Data 句柄的注入方式;当前版本推荐 app_data(web::Data::new(...)),旧写法行为差异以 docs.rs 为准。

概念解释

actix-web 数据注入经历过 API 演进:早期 data 方法负责包装,当前版本统一为 app_data 配合 Data::new。注册值的包装类型必须与提取器一致。新项目直接使用 app_data;维护旧代码时对照版本文档确认 data 是否仍可用。

原理流程

  1. 构造共享值并包装 Data。
  2. app_data 插入数据表。
  3. 提取器按类型查找句柄。
  4. 类型不一致则提取失败。

代码或图示

// 当前推荐写法
App::new()
    .app_data(web::Data::new(AppState { counter: 0 }))
    .service(web::resource("/").route(web::get().to(handler)))

常见误区

  • 混用版本教程,注册用旧 data、提取用新 Data,类型对不上。
  • app_data 插入未包装值,提取器声明 Data<T> 找不到。

追问

  • 不包装 Data 能注入普通值吗?答:app_data 可直接插入值,由对应提取器取用;共享句柄场景仍推荐 Data。
  • 如何确认当前版本 API?答:查 docs.rs actix-web 当前版本的 App 文档与 release notes,标注待确认处实测编译。

04.4.4.1-077 数据注入在 App、scope、资源三层的可见范围是什么?

一句话结论

App 层注入对全部路由可见,scope 层只对子树可见,资源层只对该资源可见;内层提取不到外层未注入的类型。

概念解释

数据作用域与中间件作用域一致。全局配置、连接池挂 App;模块级配置挂 scope;资源专属依赖挂资源。调试「Data 取不到」时先看注入层级是否覆盖当前 handler。同类型在多层重复注入时,就近覆盖关系按框架规则处理。

原理流程

  1. 在对应层级 app_data 注入。
  2. 请求进入该层级子树后数据可见。
  3. 提取器按类型在可见表中查找。
  4. 越层访问则缺失。

代码或图示

App::new()
    .app_data(web::Data::new(GlobalConfig))
    .service(
        web::scope("/admin")
            .app_data(web::Data::new(AdminConfig))
            .service(web::resource("/panel").route(web::get().to(panel)))
    )

常见误区

  • scope 内注入的数据被 App 层 handler 提取。
  • 资源级数据被同 scope 其它资源复用,实际不可见。

追问

  • 子层能覆盖父层同类型数据吗?答:按就近原则解析;具体覆盖语义以文档为准,避免同类型多层注册。
  • 全局 Data 应该在哪层注册?答:确定跨模块复用的挂 App,减少重复注入。

04.4.4.1-078 同一类型重复注入会发生什么?

一句话结论

数据表按类型索引,重复类型注册会按框架规则覆盖或产生冲突;需要多份同类型实例时应用 newtype 包装区分。

概念解释

类型索引不区分注册层级与次数,后注册值可能覆盖先注册值。实际排查中表现为 handler 拿到意外的实例。不同配置(如两个外部客户端)应定义不同结构体类型,而不是复用同一类型注册两次。

原理流程

  1. 数据表按类型记录注入值。
  2. 同类型再次注册进入。
  3. 按框架规则覆盖/拒绝。
  4. 提取器最终取到唯一索引结果。

代码或图示

// 错误:同类型注册两份,意图区分客户端但索引冲突
// .app_data(Data::new(ClientA))
// .app_data(Data::new(ClientB))

// 正确:newtype 区分
struct ClientA(InnerClient);
struct ClientB(InnerClient);

常见误区

  • 用元组或包装别名以为类型不同,实际内部类型一致。
  • 测试与生产注册不同实例,测试污染生产装配认知。

追问

  • 如何发现重复注入?答:启动后 handler 内打印实例标识;代码审查时检查同类型 app_data 调用点。
  • newtype 提取器写法?答:参数 Data<ClientA>,内部 Deref 到 InnerClient 使用。

04.4.4.1-079 Data 句柄克隆与底层值共享如何工作?

一句话结论

Data<T> 克隆产生新句柄但指向同一底层 T,句柄克隆廉价;底层值跨 worker 共享,内部可变需同步原语保护。

概念解释

工厂闭包中 move 克隆 Data 句柄进各 App 副本,底层只存一份。句柄解引用访问字段;T 自身要求可跨线程共享。需要按 worker 独立的状态不要放 Data,应放在中间件实例或 worker 局部结构。

原理流程

  1. Data::new(value) 构造共享句柄。
  2. 句柄克隆传入各 worker 与 handler。
  3. 多句柄指向同一底层值。
  4. 并发修改经内部锁/原子完成。

代码或图示

let counter = web::Data::new(Counter(AtomicU64::new(0)));

HttpServer::new(move || {
    App::new()
        .app_data(counter.clone())
        .service(web::resource("/").route(web::get().to(hit)))
})

常见误区

  • 以为克隆 Data 复制了底层值,各 worker 独立计数。
  • 底层类型含 Rc/RefCell 等非共享类型,跨线程编译失败。

追问

  • Data 底层需要 Clone 吗?答:句柄克隆不要求底层值 Clone;按需共享句柄即可,具体 bound 以文档为准。
  • 连接池为什么天然适合 Data?答:池句柄内部线程安全、可共享复用,借出连接而非共享单连接。

04.4.4.1-080 方法级与资源级 wrap 中间件如何挂载?

一句话结论

资源级 wrap 包裹该路径所有方法路由,方法路由级包裹只作用于单方法;挂载粒度按中间件作用范围选择。

概念解释

App/scope/资源/路由四级都可挂中间件。资源级中间件对同路径 GET/POST 都生效;路由级只约束某方法。顺序上外层先于内层包裹。把只属于单方法的限制挂资源层会误伤其它方法。

原理流程

  1. 在资源或路由对象上调用 wrap。
  2. 中间件加入对应包裹链。
  3. 请求按层级穿过链。
  4. 响应反向返回经过各层。

代码或图示

web::resource("/items")
    .wrap(ResourceLogger) // 资源级:所有方法
    .route(web::get().to(list))
    .route(web::post().wrap(PostAuth).to(create)) // 路由级:仅 POST

常见误区

  • 资源级与 App 级重复挂同一中间件,执行两次。
  • 路由级中间件顺序理解反了,响应头被后层覆盖。

追问

  • 路由级 wrap 接收什么类型?答:实现中间件 trait 的类型;自定义中间件按 actix-web 中间件接口实现。
  • 中间件能访问路由提取器参数吗?答:中间件在服务层运行,类型化参数在 handler 构造;跨层信息走请求扩展。

04.4.4.1-081 自定义 actix-web 中间件实现的基本结构是什么?

一句话结论

自定义中间件实现中间件 trait,包裹服务调用:在请求前后加工上下文与响应,调用内层 service 完成处理;具体 trait 名与签名以 docs.rs 当前版本为准。

概念解释

中间件形成洋葱链:外层拿到请求,调用内层 service,拿到响应后再加工。常见自研中间件:追踪 ID 注入、统一安全头、耗时统计、灰度判断。实现时注意错误响应也要经过加工逻辑,不要只处理成功响应。

原理流程

  1. 定义中间件结构体与构造器。
  2. 实现中间件 trait 的包裹方法。
  3. 请求阶段读取/补充上下文。
  4. 调用内层 service,响应阶段加工后返回。

代码或图示

// 结构示意,trait 名与方法签名待确认:以 docs.rs actix-web 当前版本为准
// struct TraceMiddleware<S> { inner: S, header: &'static str }
// impl<S> Service<Request> for TraceMiddleware<S> { ... }

常见误区

  • 只加工成功响应,错误响应缺少统一安全头。
  • 中间件内保存可变请求状态,破坏并发隔离。

追问

  • 自研中间件与用 tower 层是什么关系?答:actix-web 中间件体系自洽;跨生态复用 tower 适配的可行性按版本集成文档确认。
  • 中间件错误如何处理?答:内层返回错误后中间件可补充头或转换响应,错误传播按 service 链规则。

04.4.4.1-082 test::init_service 初始化测试服务的完整流程是什么?

一句话结论

init_service 把 App 装配为内存中的测试服务实例,完成路由、中间件、数据注入的初始化;不绑定真实端口,后续用 call_service 发请求。

概念解释

测试服务与生产共用 App 装配代码,保证测试覆盖真实路由结构。初始化是异步过程,需 .await。每个用例建议独立构造实例,避免状态串用。外部依赖在装配时替换为内存 Mock。

原理流程

  1. 构造 App 并注入测试 Data。
  2. init_service 初始化服务实例。
  3. 测试请求经服务内部路由与提取器处理。
  4. 断言响应后丢弃实例。

代码或图示

let app = test::init_service(
    App::new()
        .app_data(web::Data::new(MockDb))
        .service(web::resource("/").route(web::get().to(index)))
).await;

常见误区

  • 测试 App 与生产装配分叉,生产路由未被测试覆盖。
  • 跨用例复用同一实例,Mock 状态残留导致断言不稳定。

追问

  • init_service 会启动 worker 吗?答:测试服务在单体内处理请求,不启动多 worker;并发行为需另写压测或并发测试。
  • 测试中能访问服务内部路由表吗?答:按测试工具提供的检查接口;常规断言通过响应行为验证。

04.4.4.1-083 TestRequest 如何构造带方法、路径、头与 body 的测试请求?

一句话结论

TestRequest 提供链式构造器:get()/post() 选方法,uri() 设路径,insert_header() 加头,set_json()/set_form() 设 body,最后 to_request() 生成请求。

概念解释

测试请求构造覆盖真实客户端能发的各部分。JSON body 用 set_json,自动设 Content-Type;原始字节 body 用 set_payload。构造后交给 call_service 调用测试服务。头与 body 缺失是测试提取器失败的常见原因。

原理流程

  1. 选择方法构造器。
  2. 设置 URI 与查询串。
  3. 追加请求头与 body。
  4. to_request() 生成可调用请求对象。

代码或图示

let req = test::TestRequest::post()
    .uri("/items?page=1")
    .insert_header(("X-Trace", "t-1"))
    .set_json(&serde_json::json!({ "name": "ann" }))
    .to_request();

常见误区

  • 用 set_json 却未检查 Content-Type 自动设置情况,提取器按预期匹配失败。
  • 原始 body 忘记设编码头,表单/JSON 提取器拒绝。

追问

  • 如何构造带 Path 参数的请求?答:URI 中填实际路径段,提取器按模板绑定;模板不在测试 App 中注册会 404。
  • 测试 Cookie 怎么带?答:通过请求头构造 Cookie 头;具体辅助方法以 test 模块文档为准。

04.4.4.1-084 call_service 与 read_body 如何做响应断言?

一句话结论

call_service 把请求送入测试服务返回响应对象,read_body 读取响应 body 字节;断言状态码、头与解析后的 body 结构。

概念解释

响应对象先看状态码与头部,body 可能是流式缓冲,需 read_body 聚合成字节后再反序列化断言。JSON 接口可把 body 解析回结构体或 Value 比较字段。断言应覆盖成功与错误两类响应。

原理流程

  1. call_service(&app, req).await 得到响应。
  2. 断言 status() 与关键响应头。
  3. read_body(resp).await 取 body 字节。
  4. 反序列化并断言业务字段。

代码或图示

let resp = test::call_service(&app, req).await;
assert_eq!(resp.status(), actix_web::http::StatusCode::OK);
let body = test::read_body(resp).await;
let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
assert_eq!(value["name"], "ann");

常见误区

  • 只断言状态码,不校验 body 字段,业务错误被放过。
  • body 未读取就断言内容,拿到空缓冲。

追问

  • 响应 body 很大时 read_body 有问题吗?答:测试环境聚合缓冲可接受;超大流式响应测试应分块读取,按 Payload 测试方式处理。
  • 如何断言响应头存在?答:resp.headers().get(...) 取值比对。

04.4.4.1-085 如何在测试中断言提取器拒绝场景?

一句话结论

构造畸形 body、错误编码、缺失字段或超限请求,调用服务后断言拒绝状态码与错误体;提取器失败不进入 handler,可通过响应反推。

概念解释

拒绝场景是提取器契约的一部分:坏 JSON、非 JSON Content-Type、缺必填字段、body 超限都应返回明确 4xx。测试断言状态码区间与错误字段,而不是只看「不是 200」。自定义提取器错误映射单独覆盖。

原理流程

  1. 构造对应异常请求。
  2. call_service 得到拒绝响应。
  3. 断言状态码(400/415/413 等)。
  4. 校验错误体格式与字段。

代码或图示

let req = test::TestRequest::post()
    .uri("/items")
    .set_payload("{ broken json")
    .to_request();
let resp = test::call_service(&app, req).await;
assert!(resp.status().is_client_error());

常见误区

  • 异常请求只在手工调试时验证,未固化为测试用例。
  • 断言 500 代替 400,客户端错误被误标服务端故障。

追问

  • 如何确认请求没进 handler?答:在 handler 加计数或 Mock 记录,拒绝场景计数不增加;测试后移除。
  • 提取器错误体格式如何统一断言?答:定义错误响应结构体,测试反序列化后比对字段。

04.4.4.1-086 测试中如何注入 Data 与替换外部依赖?

一句话结论

测试 App 通过 app_data 注入 Mock 实现的共享句柄,替换数据库、外部客户端等真实依赖;接口 trait 抽象保证生产与测试可互换。

概念解释

外部依赖应通过 trait 暴露能力,生产注入真实客户端,测试注入内存 Mock。Data 注册类型在两套环境保持一致,handler 代码不变。Mock 状态在每个用例重置,避免用例间污染。

原理流程

  1. 定义外部依赖 trait。
  2. 生产实现真实客户端,测试实现内存 Mock。
  3. 测试 App 注入 Data<Mock>。
  4. 用例断言 Mock 收到的调用与产出响应。

代码或图示

trait Repo { fn find(&self, id: u64) -> Option<String>; }

struct MockRepo { items: Vec<(u64, String)> }

// 测试装配:
// .app_data(web::Data::new(MockRepo { items: vec![(1, "ann".into())] }))

常见误区

  • 测试直连开发数据库,用例依赖外部环境不稳定。
  • Mock 与生产接口签名漂移,集成时才发现不兼容。

追问

  • 异步依赖怎么 Mock?答:trait 方法返回 Future 或 async fn,Mock 用立即就绪的值返回。
  • 测试能覆盖真实连接池吗?答:集成测试可接测试库,单元/契约测试用 Mock;按测试分层选择。

04.4.4.1-087 服务启动失败有哪些常见原因,如何排查?

一句话结论

启动失败集中在端口绑定、配置缺失、Data 类型冲突、装配代码 panic 与依赖初始化异常;排查从 main 错误链与启动日志入手分层定位。

概念解释

? 传播的启动错误会保留底层 IO/配置错误链。常见:端口占用、监听地址不可用、必填配置为空、外部依赖连不通、装配期 unwrap panic。先看错误最内层 source,再核对配置与注册代码。

原理流程

  1. main 收集启动错误并输出错误链。
  2. 区分绑定、配置、依赖、装配四类来源。
  3. 核对端口/地址/配置值与依赖连通性。
  4. 检查装配期 panic 与 unwrap 点。

代码或图示

启动失败分类:
bind 失败 → 端口占用/地址/权限
配置缺失 → 必填项为空或类型不符
依赖初始化 → 数据库/客户端连不通
装配 panic → unwrap/重复注册/类型冲突

常见误区

  • 吞掉启动错误,进程退出码正常,误判服务已启动。
  • 只看最外层错误消息,未追溯 source 定位根因。

追问

  • 启动日志在哪里看路由清单?答:actix-web 启动输出已挂载路由与监听地址;日志级别按配置调整。
  • 如何在 CI 验证启动成功?答:集成测试 init_service 装配通过,或容器启动后健康检查返回 200。

04.4.4.1-088 测试中如何验证优雅停机行为?

一句话结论

优雅停机验证关注:停止接收新请求、在途请求完成、长连接与后台任务取消、超时强制退出;测试可通过服务句柄停止信号与在途请求观察。

概念解释

单元测试主要验证 handler 与装配;停机流程涉及运行时信号与连接排空,通常用集成测试或压测脚本验证。关键断言:停止后新请求被拒,在途请求拿到响应,后台任务收到取消。shutdown_timeout 与部署摘流时间对齐。

原理流程

  1. 启动测试服务或实例。
  2. 发起在途请求的同时触发停机。
  3. 观察在途请求是否完成。
  4. 验证新请求拒绝与资源释放。

代码或图示

验证点:
停止 accept 新连接
在途请求在超时内完成
WebSocket/SSE 被主动断开
后台任务循环退出
超时后剩余连接强制关闭

常见误区

  • 只验证进程能退出,不检查在途请求是否被截断。
  • 长连接未纳入停机流程,实例长期不退出。

追问

  • 后台任务如何感知停机?答:监听服务关闭钩子或取消令牌;具体挂钩 API 以当前版本文档为准。
  • 停机超时设多长合适?答:按 P99 请求耗时与部署宽限时间设定,覆盖正常在途又不拖慢发布。

04.4.4.1-089 handler 中阻塞任务隔离的落地写法是什么?

一句话结论

同步阻塞计算或 IO 用阻塞任务接口移出异步线程,await 任务句柄取回结果;阻塞数据必须满足 Send,Join 错误包装为 Web 错误。

概念解释

异步 worker 被阻塞调用占住会降低整体并发。隔离写法:spawn_blocking 闭包内做同步工作,返回可跨线程结果;handler await 句柄。阻塞数据库驱动、重计算、文件同步读取都应这样处理。任务 panic 会以 Join 错误返回,不能忽略。

原理流程

  1. 识别 handler 内阻塞操作。
  2. 提交阻塞任务并返回 Send 结果。
  3. await 句柄取回值或 Join 错误。
  4. 结果进入响应生成。

代码或图示

async fn handler() -> actix_web::Result<actix_web::HttpResponse> {
    let result = actix_web::rt::task::spawn_blocking(|| {
        // 同步阻塞工作
        42
    })
    .await
    .map_err(actix_web::error::Error::from)?;

    Ok(HttpResponse::Ok().body(result.to_string()))
}

常见误区

  • 阻塞闭包捕获非 Send 引用,跨线程编译失败。
  • Join 错误未处理,任务 panic 后响应流程中断。

追问

  • 阻塞任务池大小受什么控制?答:运行时阻塞线程池配置;具体参数以 actix-rt/运行时文档为准。
  • 哪些操作算阻塞?答:同步 IO、CPU 密集计算、阻塞锁长等待;异步驱动的 await 调用不算。

04.4.4.1-090 响应的 Content-Type 由谁决定?

一句话结论

Content-Type 由 Responder 按返回类型设置:HttpResponse 可显式指定,web::Json 固定 JSON 类型,字符串/字节有默认类型;中间件可补充但不应无理由覆盖。

概念解释

排查「前端解析失败」先核对响应头 Content-Type 与 body 实际格式。HttpResponse::Ok().json(...) 设 JSON 类型;body(String) 默认文本类型。类型化 Responder 与手写头不一致时,以实际写出层为准。

原理流程

  1. handler 选择返回类型。
  2. Responder 设置默认 Content-Type。
  3. HttpResponse 上可显式覆盖头部。
  4. 响应中间件补充安全头,写出 body。

代码或图示

// JSON 类型
HttpResponse::Ok().json(serde_json::json!({ "ok": true }))

// 显式文本类型
HttpResponse::Ok()
    .content_type("text/plain; charset=utf-8")
    .body("hi")

常见误区

  • 返回 JSON 文本却用纯文本 Responder,类型头不匹配。
  • 中间件统一改写 Content-Type,破坏接口类型契约。

追问

  • 二进制响应 Content-Type 怎么选?答:按实际格式(octet-stream、图片类型、压缩包类型)显式标注。
  • 响应 charset 在哪设置?答:文本类类型可在 Content-Type 头中指定;JSON 默认 UTF-8。

04.4.4.1-091 如何设计统一的错误响应格式?

一句话结论

定义统一错误结构体与 ResponseError 实现,按错误类型映射状态码;业务错误、提取器错误、服务错误都汇入同一格式输出。

概念解释

统一错误格式包含错误码、消息、可选字段详情。自定义业务错误枚举实现 ResponseError 生成对应 JSON;提取器错误通过配置处理器转成同一格式。避免各 handler 手写错误 body,保证前端解析一致。内部细节不外泄。

原理流程

  1. 定义错误响应 DTO(code/message/details)。
  2. 业务错误枚举实现 ResponseError。
  3. 提取器配置错误处理器映射到同一 DTO。
  4. 日志记录内部详情,对外输出安全消息。

代码或图示

#[derive(serde::Serialize)]
struct ErrorBody { code: String, message: String }

impl actix_web::ResponseError for BizError {
    fn error_response(&self) -> actix_web::HttpResponse {
        let status = match self { BizError::NotFound => StatusCode::NOT_FOUND, _ => StatusCode::INTERNAL_SERVER_ERROR };
        HttpResponse::build(status).json(ErrorBody { code: "biz".into(), message: self.to_string() })
    }
}

常见误区

  • 错误体直接携带堆栈、SQL、内部地址。
  • 客户端错误与服务端错误状态码混用,监控告警失真。

追问

  • 提取器错误如何纳入统一格式?答:在 Json/Query/Form 配置的 error_handler 中构造同一 ErrorBody 响应。
  • 错误码体系怎么设计?答:按模块与错误类别分段,对外稳定,内部日志补充上下文。

04.4.4.1-092 常见 404、400、415 状态码在 actix-web 路由/提取器层如何对照?

一句话结论

404 多为路由未命中,400 为参数/body 解析失败,415 为 Content-Type 与提取器不匹配;按状态码先分层再定位具体提取器。

概念解释

状态码是排错入口:先看是路由层还是提取器层。404 查 scope 前缀、模板、方法、guard;400 查字段类型、缺失字段、编码格式;415 查请求头 Content-Type。405 行为按当前版本默认实现核对。

原理流程

  1. 读取响应状态码。
  2. 404 → 核对路由表与匹配条件。
  3. 400 → 核对 DTO 字段与 body 格式。
  4. 415 → 核对 Content-Type 与提取器配置。

代码或图示

404:路径/方法/guard 未命中
400:反序列化失败、字段类型错、Query 解析错
415:Content-Type 与 Json/Form 提取器不符
413:body 超过限制
500:handler/提取器未预期错误

常见误区

  • 把所有 4xx 都当业务错误,忽略路由与编码层问题。
  • 错误响应不返回可定位信息,前后端来回猜测。

追问

  • 405 在 actix-web 默认怎么表现?答:以 docs.rs 当前版本实测为准;需要明确 405 时自定义默认服务或错误处理。
  • 如何在测试中固化状态码契约?答:每个异常用例断言具体状态码,而非 4xx 区间。

04.4.4.1-093 多 worker 共享状态设计有哪些陷阱?

一句话结论

多 worker 下跨请求共享必须走 Data 加线程安全内部可变性;误用单线程类型、本地缓存或非同步计数器会产生编译错误或数据竞争。

概念解释

worker 并发处理请求,共享数据的读写竞争由类型系统与同步原语约束。常见陷阱:用 Rc/RefCell、Data 内字段直接赋值、依赖本地 HashMap 做全局计数。分布式一致状态要放外部存储,本地 Data 只反映单进程。

原理流程

  1. 判断状态作用域:进程内还是集群共享。
  2. 进程内共享封装进 Data。
  3. 内部可变用 Mutex/RwLock/原子保护。
  4. 集群一致数据写入外部存储。

代码或图示

struct Metrics {
    hits: AtomicU64,
    by_path: RwLock<HashMap<String, u64>>,
}

常见误区

  • 以为 App 字段天然跨 worker 共享,实际各副本独立。
  • 本地计数器上报为集群总量,监控偏低。

追问

  • 读多写少用什么锁?答:RwLock 允许并发读;简单计数用原子类型。
  • 分布式限流/会话怎么做?答:Redis 等共享存储承载,本地 Data 只做缓存或快照。

04.4.4.1-094 配置注入为什么要在启动期 fail-fast?

一句话结论

必填配置与外部依赖在启动阶段校验、构造并注入 Data,缺失即退出;避免第一个请求才暴露配置错误,造成冷启动超时与部分失败。

概念解释

启动期错误是部署问题,应在发布早期暴露;运行期缺配置则是线上故障。配置结构体类型安全,启动期完成校验与连通性检查。可降级旁路允许后续重试,但核心依赖不应懒初始化。

原理流程

  1. 读取并解析配置结构体。
  2. 校验必填项与取值范围。
  3. 初始化依赖句柄并做连通性检查。
  4. 包装 Data 注入 App,失败则启动退出。

代码或图示

let cfg = AppConfig::load()?;
if cfg.database_url.is_empty() {
    return Err(std::io::Error::other("database_url required"));
}
let pool = DbPool::connect(&cfg.database_url).await?;
let data = web::Data::new((cfg, pool));

常见误区

  • 配置缺省用空字符串兜底,运行期分支判断才报错。
  • 连接池懒加载,并发冷启动重复建池。

追问

  • 配置校验放启动代码还是配置结构体方法?答:基础解析在抽取层,业务范围校验在启动装配代码,可单独测试。
  • 外部依赖不可达启动应退出吗?答:核心依赖 fail-fast;旁路功能可降级并后台重试。

04.4.4.1-095 与其它 Rust Web 框架相比,actix-web 路由与提取器模型有什么取舍?

一句话结论

actix-web 以 App 装配链、资源/scope 路由与 FromRequest 提取器为核心,类型约束强、生态成熟;代价是装配泛型较复杂,中间件体系与 tower 系框架不同。

概念解释

面试回答应绑定具体机制:App/HttpServer 工厂、web::resource/scope/guard、Path/Query/Json/Data 提取器、Error/ResponseError。对比时说清约定差异:提取器模型 vs 直接访问请求,资源树 vs 路由表,不要泛泛而谈性能。

原理流程

  1. 识别项目对装配约定、提取器抽象、中间件生态的要求。
  2. 对照 actix-web 的路由与提取器模型。
  3. 评估团队泛型复杂度接受度与长期维护成本。
  4. 按实测压测与生态需求选型。

代码或图示

actix-web:App 装配链、资源/scope/guard、FromRequest 提取器、Data 注入
对比框架:Service 组合层、不同提取器/请求访问抽象

常见误区

  • 横评只讲性能数字,不提类型模型与扩展点差异。
  • 把其它框架的路由习惯套到 actix-web 上排错。

追问

  • actix-web 底层运行时基于什么?答:actix-rt 运行时;与 Tokio Future 互通性以当前版本文档为准。
  • 什么场景优先选 actix-web?答:成熟生态、异步高并发、团队接受其装配模型时;具体选型结合压测。

04.4.4.1-096 编译报 Responder 或 FromRequest bound 不满足如何定位?

一句话结论

沿 handler 返回类型与参数类型追溯:返回类型未实现 Responder,参数类型未实现 FromRequest;先补 trait/derive,再检查链式装配类型是否错位。

概念解释

actix-web 泛型约束报错信息长,定位顺序:handler 签名 → 返回类型 Responder bound → 参数提取器 FromRequest bound → Data 类型一致性。常见触发:裸结构体返回、缺 Deserialize、闭包捕获不满足 Send。

原理流程

  1. 编译器指出 handler 未实现服务 trait。
  2. 检查返回类型 Responder 实现。
  3. 检查各参数提取器 bound。
  4. 修正 derive、包装类型或装配链后重新编译。

代码或图示

排查顺序:
返回值 → 是否 Json/String/HttpResponse/实现 Responder
参数 → 是否 Path/Query/Json/Data/Bytes 等提取器
Data → 注册类型与提取类型一致
链式 → 当前对象是 Resource 还是 Route

常见误区

  • 看到长泛型报错就改返回 String,掩盖真正缺失的实现。
  • 在 Resource 上调 Route 方法,类型错位报错。

追问

  • 自定义 DTO 如何满足 Responder?答:包装 web::Json 或实现 Responder trait;签名以 docs.rs 当前版本为准。
  • 闭包 handler 报 Send 错误怎么办?答:检查捕获变量所有权与跨线程约束,必要时克隆句柄进闭包。

04.4.4.1-097 运行期 Data 类型取不到如何排查?

一句话结论

核对注册类型与提取类型完全一致(包装层、Arc、newtype 都算差异),并确认注入层级覆盖当前 handler;类型不一致或越层注入都会缺失。

概念解释

Data 按类型索引,Data<Config> 与 Data<Arc<Config>> 是不同类型。排查对照:app_data 调用点、注入层级、handler 参数类型三处。测试中可先注入明确 Mock 验证提取链路,再接入真实依赖。

原理流程

  1. 列出 handler 所有 Data<T> 类型。
  2. 对照装配代码 app_data(Data::new(...)) 类型。
  3. 检查注入层级是否覆盖该路由。
  4. 修正类型包装或提升注入层级。

代码或图示

// 注册
.app_data(web::Data::new(AppState { v: 1 }))

// 提取(必须同类型)
async fn handler(state: web::Data<AppState>) -> String { state.v.to_string() }

常见误区

  • 提取参数写成 Data<&T> 或 Data<Arc<T>>,与注册不符。
  • scope 内注入,App 层 handler 提取。

追问

  • 同类型需要两份实例怎么办?答:定义不同 newtype 分别注册与提取。
  • 测试如何复现 Data 缺失?答:去掉注入构造测试服务,观察提取失败响应。

04.4.4.1-098 异步 handler 的生命周期与 Send 约束有哪些要点?

一句话结论

handler 是在运行时调度的异步任务,捕获与返回的数据必须满足 Send 与 'static 等跨任务约束;引用局部数据跨越 .await 会被编译器拦截。

概念解释

异步任务可能在不同线程间迁移,持有数据需可跨线程发送。handler 参数由提取器按请求构造;返回值与捕获闭包的引用不能借用局部临时值。跨 await 持有的非 Send 类型会编译报错,需改为共享句柄或阻塞隔离。

原理流程

  1. handler 编译为返回 Future 的异步函数。
  2. 运行时调度任务,Future 跨线程发送。
  3. 持有数据满足 Send/'static 约束。
  4. 不安全借用在编译期被拦截。

代码或图示

#[actix_web::get("/")]
async fn handler(data: web::Data<AppState>) -> String {
    let local = String::from("temp");
    // local 不跨 await 借用即可;跨线程共享用 Data 句柄
    tokio::task::yield_now().await;
    local
}

常见误区

  • 闭包捕获不可跨线程的局部引用,编译失败。
  • 在 .await 间持有锁守卫,跨线程约束与死锁风险并存。

追问

  • handler 返回值需要 'static 吗?答:返回类型按 Responder 约束;绑定到请求的局部数据不进入长期任务,具体 bound 以 trait 文档为准。
  • 非 Send 类型必须跨线程怎么办?答:放进阻塞任务内使用,或改为线程安全共享类型。

04.4.4.1-099 actix-web 接口上线前的检查清单有哪些?

一句话结论

上线前核对:路由注册与作用域、提取器契约、Data 依赖注入、错误响应格式、body 限制、中间件顺序、测试覆盖与启动配置。

概念解释

清单覆盖装配、提取、响应、配置四层。每项可核对:路由表是否含新接口,DTO 字段与前端契约一致,共享依赖已注入,错误体统一,超限有保护,中间件顺序正确,测试通过且健康检查可用。

原理流程

  1. 核对路由:路径、方法、scope 前缀、guard。
  2. 核对提取器:字段、类型、可空、编码头。
  3. 核对 Data 与中间件:类型一致、作用域正确。
  4. 核对测试与启动:用例通过、配置 fail-fast、健康检查 200。

代码或图示

上线清单:
路由/方法/guard 注册完整
DTO 契约前后端一致
Data 注入类型与层级正确
错误状态码与统一格式
body 限制与超时配置
中间件顺序与安全头
集成测试通过,健康检查可用

常见误区

  • 只在本地浏览器手测,缺少自动化契约测试。
  • 生产沿用开发宽松 limits 与调试错误格式。

追问

  • 如何确认路由已进入路由表?答:启动日志路由清单或测试 init_service 后请求命中。
  • 上线后第一波观察什么?答:4xx/5xx 比例、提取器拒绝率、耗时分布与依赖连接池水位。

04.4.4.1-100 综合:actix-web 一个请求从进入到响应写出经过哪些环节?

一句话结论

链路为:运行时启动 → App 装配(路由/中间件/Data)→ HttpServer bind 与 worker → 中间件链 → 路由模板与 guard 匹配 → 提取器构造参数 → handler 处理 → Responder 生成响应 → 中间件链返回写出。

概念解释

把本批题目串成完整生命周期:main 宏启动运行时,工厂闭包为各 worker 生成 App;请求穿过 App/scope/资源中间件,路由表匹配后提取器构造强类型参数,handler 产出经 Responder 成响应,再沿中间件链返回。排错按链路分段:起不来查启动绑定,路由不到查模板/guard,参数错查提取器,响应错查 Responder/中间件。

原理流程

  1. #[actix_web::main] 建立运行时,加载配置并注入 Data。
  2. App 工厂注册资源、scope、guard 与 wrap 中间件。
  3. HttpServer 绑定地址、启动 worker 接收连接。
  4. 请求过中间件链,路由模板与 guard 匹配,提取器构造参数。
  5. handler 处理,Responder 生成响应,中间件加工后写出。

代码或图示

main 运行时 → 配置/Data → App 装配
  → HttpServer bind + workers
    → 中间件链 → 路由/guard 匹配 → 提取器
      → handler → Responder → 中间件链 → 响应写出

常见误区

  • 排错只盯 handler,忽略中间件顺序、Data 类型与 guard 拒绝。
  • 混淆运行时、worker、handler、提取器各层职责。

追问

  • 哪一层决定请求归哪个 handler?答:路由模板加 guard 匹配链;提取器只在匹配后构造参数。
  • 新增接口需要同步检查哪些点?答:资源/方法路由与 scope 作用域、提取器 DTO 约束、Data 依赖、错误格式、中间件白名单与测试断言。