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

04.4.9.2 validator、garde 与 OpenAPI 生成

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.9 序列化校验与API契约

04.4.9.2-001 validator crate 在 Rust 后端中承担什么职责,与 Serde 如何分工?

一句话结论

validator 负责字段规则校验(长度、格式、范围、自定义规则),Serde 负责结构反序列化;两者解耦:先把输入解析成 DTO 实例,再在实例上调用校验方法收集规则错误。

概念解释

Serde 只判断「能不能解析成这个类型」,不判断「取值是否合法」。validator 通过 Validate trait 给 DTO 提供 validate 方法,按字段上标注的规则收集 ValidationErrors。规则校验发生在类型构造成功之后,因此错误可以按字段路径组织,区分结构错误与业务规则错误。

原理流程

  1. 请求体经 Serde/框架提取器反序列化为 DTO 实例。
  2. 调用 dto.validate() 执行字段规则。
  3. 全部通过返回 Ok(());违反规则聚合为 ValidationErrors。
  4. 应用层把校验错误映射为 422 字段级错误响应。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Register {
    #[validate(length(min = 3, max = 32))]
    account: String,
}

let form = Register { account: "ann".into() };
match form.validate() {
    Ok(()) => println!("valid"),
    Err(e) => println!("{e:?}"),
}

常见误区

  • 以为 validator 能在反序列化阶段拦截错误:它运行在 DTO 构造之后,结构错误仍由 Serde 路径处理。
  • 用 Serde 属性替代规则校验:rename/skip/default 等是结构映射能力,不做长度与格式判断。

追问

  • validator 与 Serde 是强制绑定关系吗?答:不是,校验 trait 作用于普通 Rust 类型,类型可以不经过 Serde 直接构造并校验。
  • 校验错误属于哪类 HTTP 错误?答:通常映射 422 Unprocessable Entity,结构解析错误多为 400/422,状态码约定在错误分层题中展开。

04.4.9.2-002 Validate trait 的方法签名是什么,ValidationErrors 如何表达失败?

一句话结论

Validate 提供 fn validate(&self) -> Result<(), ValidationErrors>;成功返回 Ok(()),失败返回按字段路径聚合的错误集合,可迭代查看每个字段违反的规则。

概念解释

derive 为结构体生成 Validate 实现,遍历标注了规则的字段并调用对应校验函数。ValidationErrors 不是单个错误,而是字段名到错误列表的聚合结构:一个字段可能同时违反多条规则,一个请求也可能多个字段不合法。迭代时能拿到字段路径与对应的 ValidationError 列表。

原理流程

  1. validate 被调用后按字段顺序执行规则。
  2. 每条规则返回 Option<ValidationError>,Some 表示违反。
  3. 错误按字段路径收入 ValidationErrors。
  4. 全部规则通过返回 Ok,否则返回聚合错误。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Login {
    #[validate(email)]
    email: String,
}

if let Err(errs) = Login { email: "bad".into() }.validate() {
    for (field, errors) in errs.errors() {
        for e in errors {
            println!("{field}: {} ({})", e.message, e.code);
        }
    }
}

常见误区

  • 把 ValidationErrors 当成单一错误消息:它是聚合容器,需要遍历字段与错误列表构造响应体。
  • 校验中途遇到第一条错误就停止:默认收集全部字段错误,便于客户端一次修正多个问题。

追问

  • errors() 返回什么类型?答:返回字段路径到错误列表的迭代视图,具体类型与方法名以当前 validator 版本文档为准(待确认)。
  • 校验方法为什么只取 &self?答:规则校验不修改 DTO,只读检查即可;需要规范化值(trim、大小写转换)应在构造或专用转换层处理。

04.4.9.2-003 引入 validator 需要在 Cargo.toml 做哪些声明?

一句话结论

声明 validator 依赖并开启 derive feature 以使用 #[derive(Validate)];版本以 docs.rs 当前版本为准,工程内锁定主版本号。

概念解释

validator 核心提供规则函数与错误类型,派生宏在独立 feature 下。不开启 derive 时只能手写 Validate 实现。规则涉及的额外依赖(如正则、邮箱校验实现)由 crate 内部管理,应用层按需确认 feature 组合。

原理流程

  1. [dependencies] 加入 validator。
  2. 开启 derive feature 获得派生宏。
  3. 代码中 use validator::Validate; 引入 trait。
  4. 在 DTO 上 derive 并标注字段规则。

代码或图示

[dependencies]
validator = { version = "*", features = ["derive"] }

常见误区

  • 忘记开 derive feature:#[derive(Validate)] 找不到宏,编译报错。
  • 把 Serde 依赖写成 validator 的传递依赖:两个 crate 分别声明,互不替代。

追问

  • 待确认:validator 当前主版本号、MSRV 与可选规则 feature 清单,验证方式为 docs.rs/validator 与 crates.io 页面。
  • 项目同时用 garde 时两个依赖能共存吗?答:可以,两者 trait 与错误类型独立,按 DTO 选择其一或局部混用。

04.4.9.2-004 #[derive(Validate)] 与字段规则属性的书写结构是什么?

一句话结论

类型上 derive Validate,每个需要校验的字段写 #[validate(...)],规则以函数参数形式给出阈值与条件;嵌套类型用 nested 触发自身校验。

概念解释

派生宏读取字段类型与规则标注,生成遍历字段的 validate 实现。规则属性内部按规则名传参,例如长度传 min/max,范围传数值边界。字段类型必须与规则匹配:length 用于字符串/集合,range 用于数值。

原理流程

  1. 结构体标注 #[derive(Validate)]。
  2. 字段上写 #[validate(length(...), email)] 等规则组合。
  3. 派生生成代码逐字段调用规则函数。
  4. 违反规则的错误收入聚合容器。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct CreateProduct {
    #[validate(length(min = 2, max = 64))]
    title: String,
    #[validate(range(min = 0.01, max = 99999.0))]
    price: f64,
    #[validate(nested)]
    meta: Meta,
}

#[derive(Validate)]
struct Meta {
    #[validate(length(max = 128))]
    remark: String,
}

常见误区

  • 规则套错字段类型:数值字段用 length、字符串字段用 range 会编译或校验期报错。
  • 多个规则写在一个属性内却漏逗号:派生宏解析失败,按编译提示修正语法。

追问

  • 结构体内不写规则的字段会被检查吗?答:不标注规则即跳过该字段校验,并非所有字段强制参与。
  • 枚举类型如何校验?答:validator 主要面向结构体字段;枚举取值合法性通常在业务层或自定义规则中判断,具体支持以文档为准。

04.4.9.2-005 email 规则校验的是什么,能替代真实邮件验证吗?

一句话结论

email 规则按邮箱格式语法校验字符串形态,不等于邮件可达性验证;真实送达需要发送验证链接或调用第三方校验服务。

概念解释

格式校验检查 本地部分@域名 的语法结构,拦截明显写错的账号。它不检查域名是否注册、邮箱是否存在、收件箱是否活跃。生产环境通常组合:格式规则 + 注册后邮件链接验证 + 风控规则,不能把格式规则当成用户真实性证明。

原理流程

  1. 字段字符串传入 email 规则实现。
  2. 规则按邮箱语法解析本地部分与域名。
  3. 语法不符返回带 code = "email" 的 ValidationError。
  4. 应用层在响应中返回格式错误提示。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Contact {
    #[validate(email)]
    address: String,
}

常见误区

  • 以为通过 email 规则就不会退信:格式合法但域名无效、邮箱停用同样无法送达。
  • 用严格正则替代 crate 实现:邮箱语法边界复杂,维护正则成本高,应优先使用库规则。

追问

  • 待确认:validator 当前版本 email 规则使用的校验实现(正则或专用解析库),验证方式为 docs.rs/validator 规则文档。
  • 手机号校验用哪个规则?答:有 phone 类规则(名称与覆盖地区以当前文档为准,待确认);跨地区手机号建议在自定义规则或业务服务层处理。

04.4.9.2-006 length 规则的 min/max/char_count/bytes 分别约束什么?

一句话结论

length 按字符数或字节数约束字符串与集合长度;min/max 给上下界,char_count 按 Unicode 字符计数,bytes 按字节计数,集合默认按元素个数。

概念解释

字符串长度存在三种口径:Unicode 字符数、UTF-8 字节数、用户感知的显示宽度。中文、emoji 等多字节字符在不同口径下结果不同。接口约定必须说明按哪种口径校验,避免前后端边界不一致。集合类型的长度对应元素数量。

原理流程

  1. 规则读取字段长度口径与边界参数。
  2. 字符串:按字符或字节计算长度;集合:统计元素数。
  3. 超出边界返回长度规则错误。
  4. 错误 params 中通常带边界值,供响应消息模板使用。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Post {
    #[validate(length(min = 1, max = 200, char_count))]
    title: String,
    #[validate(length(min = 1, max = 10000))]
    tags: Vec<String>,
}

常见误区

  • 中文标题按字节数限制:字节口径下中文占 3 字节,字符数限制会比预期更紧。
  • 把集合元素数与字符串长度混为一谈:二者调用同一规则,统计对象不同。

追问

  • 待确认:当前版本 length 规则参数名(min/max/equal/char_count/bytes)完整清单,验证方式为 validator 规则文档。
  • 显示宽度(如全角半角)需要校验吗?答:字符数与字节数都不等同显示宽度,此类需求需自定义规则按排版库计算。

04.4.9.2-007 range 规则如何约束数值字段的上下界?

一句话结论

range(min = "...", max = "...") 对整数或浮点数值字段做闭区间检查,越界返回范围错误;边界值是否包含在参数语义中,以当前库文档为准。

概念解释

数值字段常见约束:年龄非负、价格大于零、分页页码与每页条数有上限。range 直接比较数值大小,避免手写 if v < min || v > max 样板代码。浮点比较存在精度问题,金额类字段建议用定点类型并在业务层复核。

原理流程

  1. 规则读取 min/max 边界参数。
  2. 字段值与边界比较。
  3. 小于下界或大于上界返回 range 错误。
  4. 错误参数携带上下界,用于生成提示消息。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Page {
    #[validate(range(min = 1, max = 100))]
    page_size: u32,
    #[validate(range(min = 0.0))]
    amount: f64,
}

常见误区

  • 用 range 约束字符串长度:类型不符,应改用 length。
  • 浮点边界直接等值比较:价格尾差可能导致合法值被拒,边界设计需考虑精度。

追问

  • 只需要下界或上界怎么办?答:省略另一侧参数,规则只检查给定边界;具体可选参数以文档为准。
  • 数值是包装类型(新类型 ID)时怎么校验?答:在自定义规则中解包比较,或在 DTO 层转换为基础数值后套用规则。

04.4.9.2-008 regex 规则如何传正则表达式,编译时机有什么影响?

一句话结论

regex(path = "...") 或字符串字面量(写法以当前版本为准)绑定一个正则表达式;正则在规则执行时参与匹配,重复编译会带来性能开销,复杂模式应复用已编译实例。

概念解释

正则规则用于格式无法被内置规则覆盖的场景:订单号编码、自定义编号格式等。表达式需要在编译期或首次使用时编译为正则实例,每次校验重复解析字符串会浪费 CPU。热路径上应评估内置规则或预编译正则方案。

原理流程

  1. 规则属性绑定正则表达式来源。
  2. 校验时编译或取得正则实例。
  3. 对字段字符串执行匹配。
  4. 不匹配返回 regex 规则错误。

代码或图示

use validator::Validate;

const SKU_RE: &str = r"^[A-Z]{2}-\d{6}$";

#[derive(Validate)]
struct Sku {
    #[validate(regex(path = "SKU_RE"))]
    code: String,
}

常见误区

  • 在高频接口内每次手写解析正则:应确认库内部缓存行为,必要时自定义规则持有预编译实例。
  • 正则写得过于宽泛或嵌套过深:回溯灾难可被恶意输入利用,模式需评审。

追问

  • 待确认:validator 当前版本 regex 规则的参数写法(字符串字面量还是 path 常量)与编译缓存行为,验证方式为 docs.rs/validator。
  • 正则校验失败错误如何提示?答:错误 code 为规则名,params 携带模式信息;面向用户的消息在响应层模板化。

04.4.9.2-009 除 email/length/range/regex 外,validator 还有哪些常用字符串规则?

一句话结论

常用字符串规则包括 url、contains、starts_with、ends_with、required 等;完整规则清单以当前版本文档为准,不确定的规则标注待确认。

概念解释

内置规则覆盖最常见的格式与包含判断:URL 语法校验、子串包含、前后缀匹配、可选字段必填。业务特定格式(身份证、内部编号)走 custom 规则。规则名称与参数随版本演进,使用前核对文档,不凭记忆写属性。

原理流程

  1. 按字段语义选择内置规则。
  2. 规则属性传入匹配目标或边界参数。
  3. 校验执行对应字符串判断。
  4. 不满足时生成带规则 code 的错误。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Resource {
    #[validate(url)]
    link: String,
    #[validate(starts_with(prefix = "https://"))]
    secure_link: String,
    #[validate(contains(substr = "ann"))]
    label: String,
}

常见误区

  • 规则参数名凭记忆书写:参数名版本间可能调整,编译通过后仍应对照文档确认语义。
  • 用多个字符串规则堆叠表达复杂格式:可读性差,复杂格式应集中到一条自定义规则。

追问

  • 待确认:当前版本 url、contains、starts_with、ends_with、required、credit_card、phone 等规则的准确参数名与适用类型,验证方式为 validator 规则章节。
  • 内置规则覆盖不到时的扩展点是什么?答:custom 规则调用自定义校验函数,返回 Option<ValidationError>。

04.4.9.2-010 custom 规则如何写自定义校验函数,签名有什么要求?

一句话结论

custom(function = "path") 指向一个签名为 &T -> Option<ValidationError> 的函数;返回 None 表示通过,返回 Some(ValidationError) 表示违反规则。

概念解释

内置规则无法表达业务约束(枚举值白名单、跨字段关联、编码格式)时,用 custom 挂接函数。函数只读字段值,构造错误时可设置 code、message 与 params。需要访问外部上下文(数据库、配置)的校验不适合放在无参函数内,应放到服务层。

原理流程

  1. 定义自由函数,参数为字段类型引用。
  2. 函数执行自定义判断。
  3. 通过返回 None;违反返回 Some(ValidationError)。
  4. 字段属性 custom(function = "模块::函数") 绑定。

代码或图示

use validator::{Validate, ValidationError};

fn odd(v: &u32) -> Option<ValidationError> {
    if v % 2 == 1 { None } else { Some(ValidationError::new("not_odd")) }
}

#[derive(Validate)]
struct Ticket {
    #[validate(custom(function = "odd"))]
    seq: u32,
}

常见误区

  • 自定义函数返回布尔值而不是 Option<ValidationError>:签名不匹配,派生调用会编译报错。
  • 在 custom 函数里查库或调用远程服务:校验函数应保持纯判断,IO 型规则放到服务层并单独组织错误。

追问

  • 错误 message 如何设置?答:构造 ValidationError 后设置消息字段,或通过消息模板按 code 映射;具体 API 以当前版本为准(待确认)。
  • 自定义规则能访问整个 DTO 吗?答:字段级 custom 只收到当前字段值;跨字段校验见跨字段专题题,通常在 validate 之外的服务层方法处理。

04.4.9.2-011 nested 规则如何触发嵌套结构体自身的校验?

一句话结论

字段标注 #[validate(nested)] 后,校验调用该字段类型的 validate 方法,把内层聚合错误按字段路径并入外层 ValidationErrors。

概念解释

DTO 常嵌套子结构:地址、明细行、附件信息。外层 validate 默认只检查外层字段标注的规则,不会自动递归内层类型。nested 显式声明递归边界,内层违反的错误以字段路径(如 items.0.name)出现在聚合结果中。

原理流程

  1. 外层校验遇到 nested 字段。
  2. 调用内层类型的 validate(&self)。
  3. 内层 ValidationErrors 按路径并入外层聚合容器。
  4. 外层继续处理其余字段。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Order {
    #[validate(nested)]
    address: Address,
}

#[derive(Validate)]
struct Address {
    #[validate(length(min = 2))]
    city: String,
}

常见误区

  • 忘记写 nested:内层规则永远不执行,问题延迟到数据库或业务层暴露。
  • 内层类型没有 derive Validate:nested 调用找不到 trait 方法,编译报错。

追问

  • 集合里的元素如何递归校验?答:集合字段配合元素类型校验规则,具体集合内元素递归写法以当前 validator 文档为准(待确认)。
  • 嵌套错误路径如何展示给客户端?答:响应体按字段路径组织,例如 address.city,便于前端定位输入框。

04.4.9.2-012 required 规则对 Option 字段起什么作用?

一句话结论

required 要求 Option 字段必须为 Some,None 视为违反规则;用于类型可选但业务必填的字段场景。

概念解释

字段用 Option<T> 是类型层面允许缺失,但业务上可能仍要求必须传值。required 在这种情况下把 None 判为错误,与类型本身的可空性区分开。非 Option 字段缺失在反序列化阶段就已报错,不需要该规则。

原理流程

  1. 校验读取 Option 字段值。
  2. None 返回 required 错误。
  3. Some(v) 继续执行该字段上的其他规则。
  4. 错误聚合到字段路径下。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Profile {
    #[validate(required)]
    nickname: Option<String>,
}

常见误区

  • 对非 Option 字段写 required:类型已保证有值,规则冗余。
  • 用 required 代替反序列化必填检查:结构缺失仍由 Serde 报错,两层职责不同。

追问

  • Some("") 算通过 required 吗?答:required 只判断是否为 Some,空串需要再叠加 length 规则拦截。
  • 待确认:当前版本 required 规则的适用类型与错误 code,验证方式为 validator 文档。

04.4.9.2-013 validator 内置规则的完整清单如何核对,避免使用已废弃规则?

一句话结论

规则清单属于版本敏感信息,使用前查 docs.rs/validator 当前版本的规则章节;清单外的规则标注「待确认」并写明验证点,不凭记忆编造规则名与参数。

概念解释

内置规则覆盖格式、长度、范围、包含关系与部分业务格式。版本升级时可能新增、重命名或废弃规则。项目中应建立规则使用清单:每个 validate(...) 属性对应文档中的规则条目,升级时回归校验行为。

原理流程

  1. 打开 validator 当前版本文档规则列表。
  2. 对照代码中的规则名与参数。
  3. 文档未覆盖的用法标记待确认,写最小示例验证。
  4. 升级依赖后运行校验规则测试,回归合法/非法样例。

代码或图示

待确认条目示例:
- credit_card:卡号格式校验是否在当前版本内置
- phone:支持的地区号与校验实现
- 各规则参数名与默认边界
验证方式:docs.rs/validator 规则章节 + 最小编译示例

常见误区

  • 把其他语言生态的规则名直接套到 Rust validator:规则命名与参数可能不同。
  • 升级依赖后不回归规则测试:废弃或行为变更的规则可能静默改变校验结果。

追问

  • 项目如何记录规则版本基线?答:在依赖锁定文件与工程文档中记录 validator 版本,规则用法集中在 DTO 评审时检查。
  • 文档缺失时最稳妥的写法是什么?答:用 custom 函数自己实现判断,避免依赖不确定的内置规则。

04.4.9.2-014 ValidationError 携带哪些信息,如何用于错误响应?

一句话结论

错误条目包含规则 code、可选 message 与 params 参数表;响应层按 code 映射用户提示,params 提供边界值等模板变量,message 可直接补充说明。

概念解释

ValidationError 是单条规则违反的描述:code 标识规则类型(如 length、email),message 是可选的具体文案,params 存放规则参数(min、max、模式等)。机器可读的 code 用于前端定位与国际化,人类可读 message 用于直接展示,两者分层使用。

原理流程

  1. 规则违反时构造 ValidationError。
  2. 填入 code、message 与 params。
  3. 错误收入字段路径下的错误列表。
  4. 响应层遍历聚合容器,按 code 选择消息模板并替换 params。

代码或图示

use validator::ValidationError;

let mut e = ValidationError::new("length");
e.message = Some("长度超出范围".into());
e.params.insert("max".into(), 200.into());

常见误区

  • 把内部 code 直接展示给终端用户:code 是机器标识,文案应经国际化模板转换。
  • 把 params 里的边界值硬编码进消息:参数应从错误条目读取,避免与规则配置不一致。

追问

  • 待确认:当前版本 ValidationError 字段类型(Cow/HashMap 等)与构造方法,验证方式为 docs.rs/validator。
  • 一条字段违反多条规则如何呈现?答:字段错误列表包含多条 ValidationError,响应体可按数组返回全部问题。

04.4.9.2-015 ValidationErrors 如何按字段路径聚合,遍历结构是什么?

一句话结论

聚合容器把错误按字段路径分组:外层字段名、嵌套路径与集合索引组成键,值是该路径下的错误列表;遍历先取字段路径,再取错误条目。

概念解释

嵌套 DTO 与集合场景下,错误路径需要定位到具体位置,例如 items.2.sku。ValidationErrors 内部按路径组织错误,提供迭代视图访问字段名与错误列表。响应契约应约定路径字符串格式,前端据此高亮对应输入项。

原理流程

  1. 各字段规则违反时生成错误条目。
  2. 派生代码把条目挂到对应字段路径下。
  3. 嵌套与集合路径由 nested/集合校验逐级拼接。
  4. 应用层遍历路径与错误列表构造响应 JSON。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Cart {
    #[validate(nested)]
    items: Vec<Item>,
}

#[derive(Validate)]
struct Item {
    #[validate(length(min = 1))]
    sku: String,
}

常见误区

  • 响应体只返回第一条错误:聚合容器保留全部问题,一次返回多个字段错误体验更好。
  • 路径格式前后端约定不一致:前端无法定位输入框,契约文档需固定路径拼接规则。

追问

  • 待确认:当前版本访问字段错误与集合索引错误的 API 名称,验证方式为 validator 文档与示例。
  • 路径中字段名用 Rust 名还是对外名?答:响应应使用对外契约名(Serde rename 后),映射在错误转换层完成。

04.4.9.2-016 校验失败如何转换为 HTTP 422 字段级错误响应?

一句话结论

应用层捕获 ValidationErrors,遍历字段路径与错误条目,组装成统一错误体(错误码、字段路径、提示消息),返回 422 状态码;结构解析错误走另一条拒绝路径。

概念解释

422 表示「语法可解析但语义/规则不合法」。转换层把 validator 内部类型映射为对外错误契约:字段路径、规则 code、本地化消息。响应结构应与其他错误类型一致,便于前端统一处理。反序列化失败的结构错误(缺字段、类型不符)通常由提取器拒绝路径处理,状态码按框架约定。

原理流程

  1. DTO 构造成功后调用 validate。
  2. 收到 Err(ValidationErrors),进入错误转换层。
  3. 遍历路径与错误,按 code 选择消息模板,组装字段错误数组。
  4. 返回 422 与统一错误体;校验通过才进入业务处理。

代码或图示

use serde::Serialize;
use validator::Validate;

#[derive(Serialize)]
struct FieldIssue { field: String, code: String, message: String }

#[derive(Serialize)]
struct ErrorBody { code: String, issues: Vec<FieldIssue> }

fn to_422(errs: validator::ValidationErrors) -> ErrorBody {
    let issues = errs.errors().iter().flat_map(|(field, list)| {
        list.iter().map(|e| FieldIssue {
            field: field.clone(),
            code: e.code.to_string(),
            message: e.message.as_deref().unwrap_or("invalid").to_string(),
        })
    }).collect();
    ErrorBody { code: "validation_failed".into(), issues }
}

常见误区

  • 校验错误返回 500:属于客户端可纠正的输入问题,应映射 4xx。
  • 错误体直接序列化内部 ValidationErrors 结构:内部类型字段名与格式不稳定,应显式映射为对外契约。

追问

  • 400 与 422 如何分工?答:结构/类型解析失败常用 400,规则校验失败常用 422;具体约定在项目错误分层中固定,框架默认行为需核对当前版本。
  • 校验失败是否记录日志?答:记录摘要与请求 ID 便于排查,不把完整敏感输入写入日志。

04.4.9.2-017 校验与反序列化的顺序是什么,两类错误如何分界?

一句话结论

先反序列化:Serde 把输入解析为 DTO 实例,失败是结构错误;再校验:在实例上执行规则,失败是规则错误。两层错误类型、状态码与响应结构分别组织。

概念解释

结构错误包括缺必填字段、类型不符、枚举标签未知、未知字段被拒绝;规则错误包括长度越界、格式不符、范围超限、自定义规则不通过。顺序不能颠倒:规则校验需要一个类型完整的实例,反序列化都失败时无从取值检查。

原理流程

  1. 框架提取器读取 body 并调用 Serde 反序列化。
  2. 结构不符:提取器拒绝,返回结构错误响应。
  3. 构造成功:进入 handler 或服务层调用 validate。
  4. 规则违反:转换为 422 字段错误;通过后执行业务逻辑。

代码或图示

请求 body
  → 反序列化(Serde):失败 = 结构错误(400/422,提取器拒绝)
  → DTO 实例
  → 规则校验(validator/garde):失败 = 规则错误(422,字段级)
  → 业务处理

常见误区

  • 把规则校验塞进 Serde 自定义反序列化:两层职责混淆,错误路径与定位都变复杂。
  • 反序列化宽松到任何输入都能构造实例,把问题留给校验层:结构约束(类型、必填)应在类型层表达。

追问

  • 表单字段都是字符串如何做类型校验?答:反序列化按 DTO 目标类型转换,转换失败属于结构错误;转换成功后的取值规则走校验层。
  • 哪一层负责 trim/规范化?答:规范化不属于校验结论,可在 DTO 构造后、规则校验前的转换步骤完成。

04.4.9.2-018 集合字段(Vec<T>)如何校验元素与整体长度?

一句话结论

集合字段可标注 length 约束元素个数;元素类型自身的规则通过嵌套递归校验执行,具体集合内元素递归写法以当前 validator 文档为准。

概念解释

列表字段有两层约束:整体元素数量上限(防止超长数组),每个元素内部字段合法(明细行、标签项)。整体长度用集合口径的 length,元素合法性依赖元素类型的 Validate 实现并按集合校验机制递归。

原理流程

  1. 字段标注集合长度规则。
  2. 校验统计元素个数并检查边界。
  3. 逐个元素触发类型校验,错误带集合索引路径。
  4. 聚合返回所有元素中的违反项。

代码或图示

use validator::Validate;

#[derive(Validate)]
struct Batch {
    #[validate(length(min = 1, max = 20))]
    items: Vec<Line>,
}

#[derive(Validate)]
struct Line {
    #[validate(length(min = 1, max = 32))]
    sku: String,
}

常见误区

  • 只限制集合长度不校验元素:非法元素进入业务层后才暴露。
  • 元素类型没有 Validate 实现:递归无规则可执行,编译或运行期按库行为暴露问题。

追问

  • 待确认:当前版本 validator 对 Vec/Option<Vec> 元素递归校验的属性写法,验证方式为 validator 集合校验文档。
  • 集合元素数量上限应在哪一层再加保险?答:DTO 规则给业务边界,请求 body 大小限制在框架/中间件层兜底,两层互补。

04.4.9.2-019 garde crate 的定位是什么,与 validator 的设计差异在哪?

一句话结论

garde 是另一套 Rust 校验库,强调上下文(context)传递与报告(Report)式错误聚合;规则挂在字段上,校验时可传入外部上下文参与判断。

概念解释

与 validator 类似,garde 通过派生宏为类型生成校验实现。差异点:garde 的 validate 接收一个上下文参数,便于跨字段或依赖外部数据的规则;错误以 Report 结构组织,错误条目带路径、消息、code 与参数。选型时两者都应在真实 DTO 上试用,比较规则覆盖、错误模型与维护活跃度。

原理流程

  1. 类型 derive garde 的 Validate。
  2. 字段标注 garde 规则。
  3. 调用 validate(&context),上下文参与规则判断。
  4. 返回 Result<(), Report<Error>>,失败遍历报告构造响应。

代码或图示

// feature 名与 derive 方式以 garde 当前 docs.rs 文档为准(待确认)
use garde::Validate;

#[derive(Validate)]
struct Draft {
    #[garde(length(min = 1, max = 64))]
    title: String,
}

常见误区

  • 不核对版本就照搬规则属性:garde 与 validator 规则名、参数名不通用。
  • 把 garde 上下文当成数据库连接池入口:上下文用于校验所需的只读数据,IO 型规则仍应放到服务层。

追问

  • 待确认:garde 当前版本的 crate 名、derive feature、Validate trait 方法签名与错误类型名,验证方式为 docs.rs/garde。
  • 两个库能否在同一项目混用?答:技术上可以按模块选择,但错误模型与规则风格应统一,避免维护两套校验习惯。

04.4.9.2-020 garde 的派生宏与字段规则如何书写?

一句话结论

类型上 derive Validate,字段规则写在 #[garde(...)] 属性内,规则名与参数按 garde 文档书写;校验方法在传入上下文后执行全部字段规则。

概念解释

garde 的属性命名空间与 validator 不同,规则覆盖长度、范围、格式、嵌套等常见维度。字段类型需与规则匹配,嵌套类型通过 nested 规则递归。具体规则名清单与参数属于版本敏感信息,使用前核对当前版本文档。

原理流程

  1. 结构体标注 garde derive。
  2. 字段写长度、范围、格式等规则。
  3. 调用校验方法,派生代码逐字段执行规则。
  4. 违反条目收入 Report,成功返回 Ok(())。

代码或图示

use garde::Validate;

#[derive(Validate)]
struct Filter {
    #[garde(range(min = 1, max = 100))]
    page: u32,
    #[garde(length(min = 1))]
    keyword: String,
}

常见误区

  • 把 validator 的 validate(...) 写法搬到 garde:属性命名空间不同,编译不通过。
  • 规则参数名凭记忆填写:以 garde 当前文档为准,编译后仍需对照规则语义。

追问

  • 待确认:garde 规则属性前缀(garde 还是其他命名)与完整规则清单,验证方式为 docs.rs/garde 示例章节。
  • 字段规则组合写法有什么限制?答:多个规则在同一属性内逗号分隔,具体组合约束以派生宏文档为准。

04.4.9.2-021 garde 提供哪些常用规则,分别约束什么?

一句话结论

garde 常用规则覆盖 required、length、range、email、url、pattern、nested 等:必填、长度、数值范围、格式、正则模式与递归嵌套,完整清单以当前版本文档为准。

概念解释

规则按字段类型分组:字符串适用长度、格式、模式;数值适用范围;可选字段适用必填;嵌套类型适用递归。pattern 对应正则匹配,nested 触发内层类型校验。规则命名与参数和 validator 不通用,迁移时需逐字段对照。

原理流程

  1. 按字段类型选择规则类别。
  2. 属性内传入边界或模式参数。
  3. 校验执行对应判断,违反生成错误条目。
  4. 嵌套规则把内层报告并入外层。

代码或图示

use garde::Validate;

#[derive(Validate)]
struct Account {
    #[garde(required, email)]
    email: Option<String>,
    #[garde(range(min = 0, max = 120))]
    age: u8,
    #[garde(pattern(r#"^\w{3,16}$"#))]
    login: String,
}

常见误区

  • 规则套错类型:数值字段用长度规则、字符串字段用范围规则,编译或校验期暴露问题。
  • 把待确认规则写进核心 DTO:文档未核对的规则应先在最小示例验证行为。

追问

  • 待确认:garde 当前版本规则名、参数名与别名形式,验证方式为 docs.rs/garde 规则列表。
  • 集合元素长度如何约束?答:在元素类型字段上写规则,集合递归校验时逐个执行;集合整体数量规则按文档对应属性配置。

04.4.9.2-022 garde 的上下文(context)机制解决什么问题?

一句话结论

上下文是校验时传入的只读数据,供规则访问跨字段关联信息或外部配置;不需要把这些数据塞进 DTO 字段,也不需要在校验函数里持有全局状态。

概念解释

有些规则判断依赖 DTO 之外的信息:起止时间比较需要另一个字段、唯一性校验需要已有集合、白名单来自配置。garde 把上下文作为 validate 参数传入,规则实现可以读取它。上下文应保持只读与轻量,数据库查询这类重 IO 不应伪装成上下文规则。

原理流程

  1. 构造校验上下文(配置、当前用户、关联值等只读数据)。
  2. 调用 dto.validate(&ctx)。
  3. 规则实现从上下文取所需数据参与判断。
  4. 违反规则生成错误条目并入报告。

代码或图示

use garde::Validate;

struct Ctx { max_tags: usize }

#[derive(Validate)]
struct Post {
    #[garde(length(max = ctx.max_tags))]
    tags: Vec<String>,
}

常见误区

  • 上下文持有可变状态或连接池句柄:上下文应只读共享,重资源由服务层管理。
  • 在上下文规则里做远程调用:校验路径被阻塞,跨服务规则应放到服务层事务外完成。

追问

  • 待确认:garde 上下文在规则函数中的传递方式与泛型约束,验证方式为 garde 自定义规则文档。
  • 不使用上下文的规则写法有区别吗?答:基础规则不依赖上下文,传入默认或单元上下文即可,具体签名以文档为准。

04.4.9.2-023 validate 返回的 Report 结构如何组织与遍历?

一句话结论

校验成功返回 Ok(()),失败返回 Report<Error>;报告按字段路径收集错误条目,提供长度判断与迭代访问方式,供应用层构造错误响应。

概念解释

Report 是 garde 的聚合错误容器,角色类似 validator 的 ValidationErrors:一个字段可有多条错误,多个字段同时违反。遍历报告先定位字段路径,再读取错误条目。报告类型与迭代 API 名称属于版本敏感信息,使用前核对当前文档。

原理流程

  1. 派生校验代码执行全部规则。
  2. 违反条目按路径收入 Report。
  3. 应用层判断报告是否为空。
  4. 非空时遍历路径与条目,映射为对外错误体。

代码或图示

use garde::Validate;

#[derive(Validate)]
struct Form {
    #[garde(length(min = 2))]
    name: String,
}

let report = Form { name: "a".into() }.validate(&());
if let Err(r) = report {
    for item in r.iter() {
        println!("{item:?}");
    }
}

常见误区

  • 把 Report 当成单条错误:它是聚合容器,需要遍历才能得到全部问题。
  • 直接把内部 Report 序列化给客户端:内部结构不稳定,应显式映射为对外错误契约。

追问

  • 待确认:当前版本 Report 的字段访问方法(iter/inner/len 等)与错误条目类型名,验证方式为 docs.rs/garde。
  • Report 与 validator 的 ValidationErrors 能互换吗?答:类型独立,跨库迁移需要重写错误转换层。

04.4.9.2-024 garde 错误条目包含哪些字段信息?

一句话结论

错误条目通常包含路径、消息、规则 code、参数表与触发值;路径定位到嵌套/集合位置,code 标识规则,params 携带边界等参数,value 记录违反时的值。

概念解释

对外错误响应需要机器可读标识与人类可读文案两层:code 与 params 供模板与国际化使用,message 提供直接说明,路径供前端定位输入项。记录触发值便于排查,但敏感字段值不应进入响应体与日志。

原理流程

  1. 规则违反时构造错误条目。
  2. 填入路径、code、params 与可选 message/value。
  3. 条目挂入对应路径的报告列表。
  4. 响应层按契约选择暴露哪些字段。

代码或图示

错误条目示例(字段名以 garde 当前文档为准):
path: "items.2.sku"
code: "length"
params: { "min": 1, "max": 32 }
message: 可选的直接说明

常见误区

  • 把触发值原样返回给客户端:敏感或过长的值应脱敏或省略。
  • 错误条目只存 message 不存 code:国际化与前端定位缺少机器标识。

追问

  • 待确认:garde 错误条目的准确字段名与可访问 API,验证方式为 docs.rs/garde 错误类型章节。
  • 多条错误按什么顺序排列?答:按字段遍历与规则执行顺序收集,响应契约不要依赖条目顺序,前端应按路径归组。

04.4.9.2-025 garde 与 validator 如何选型?

一句话结论

两者都能完成字段规则校验:validator 生态与文档积累更深,garde 上下文机制与报告模型更灵活;选型看规则覆盖、错误模型、维护活跃度与团队熟悉度,并用真实 DTO 做对比验证。

概念解释

对比维度:内置规则数量与参数形式、跨字段/上下文支持、错误聚合结构、派生宏成熟度、依赖体量、社区活跃度。不要只看 star 数:规则是否覆盖项目常用格式、错误类型能否顺畅映射 422 响应更关键。

原理流程

  1. 列出项目 DTO 上的规则类型清单。
  2. 在两个库的最小示例中实现同一组规则。
  3. 比较错误输出、代码可读性与编译反馈。
  4. 核对当前版本维护状态与升级风险后定选型。

代码或图示

对比维度:
- 内置规则:email/url/length/range/regex/嵌套
- 上下文与跨字段支持
- 错误聚合与字段路径表达
- 依赖体量与 feature 组合
- 文档示例与当前版本活跃度

常见误区

  • 凭印象选择「流行度高」的库:项目规则匹配度才是首要标准。
  • 选型后混用两套错误模型:团队应统一在一个库内,降低维护成本。

追问

  • 已有项目从 validator 切到 garde 成本多大?答:DTO 属性与错误转换层需要重写,服务层业务校验不受影响。
  • 待确认:两个库当前版本号、MSRV 与最近发布时间,验证方式为 crates.io 与 docs.rs。

04.4.9.2-026 garde 如何写自定义规则?

一句话结论

内置规则不足时,按 garde 文档约定实现规则函数或自定义校验器,挂到字段属性上;函数接收字段值与上下文,返回错误条目或通过结果。

概念解释

自定义规则承接业务格式:内部编号编码、状态白名单、组合约束。规则实现保持纯判断,需要外部数据时经上下文传入。具体函数签名、错误构造方式与属性写法以 garde 当前版本文档为准,属于待确认项。

原理流程

  1. 实现规则函数:接收字段引用与上下文。
  2. 判断通过返回成功结果;违反构造错误条目。
  3. 字段属性绑定规则路径。
  4. 校验执行时调用函数并把结果收入报告。

代码或图示

// 签名与属性写法待确认,以 docs.rs/garde 自定义规则章节为准
fn even(v: &u32) -> garde::Result {
    if v % 2 == 0 { Ok(()) } else { Err(garde::Error::new("not_even")) }
}

常见误区

  • 自定义规则里访问数据库或发 HTTP:重 IO 应放服务层,规则只做可快速完成的判断。
  • 凭记忆编写函数签名:先查文档最小示例,确保返回类型与错误构造方式匹配。

追问

  • 自定义规则能访问兄弟字段吗?答:字段级规则主要看当前字段;跨字段比较在整体校验方法或服务层处理,具体能力以文档为准。
  • 规则复用如何组织?答:跨 DTO 共用的规则函数放在校验工具模块,属性按路径引用。

04.4.9.2-027 garde 对 Option、集合与嵌套类型分别如何处理?

一句话结论

Option 配合 required 规则区分可选与必填;集合在元素类型上写规则并递归校验;嵌套结构体通过 nested 规则触发自身校验,空值跳过策略按规则文档约定。

概念解释

可空字段、列表字段、子结构字段是 DTO 的三种复合形态。garde 对 None 的默认处理(跳过后续规则还是报错)取决于是否标注必填;集合逐个元素校验;嵌套类型递归进入自身 validate。每种形态的行为需在项目测试中固定样例。

原理流程

  1. 读取字段值:None/空集合/结构体实例。
  2. Option:按 required 规则决定报错还是跳过。
  3. 集合:遍历元素执行元素类型规则。
  4. 嵌套:调用内层校验,报告按路径并入。

代码或图示

use garde::Validate;

#[derive(Validate)]
struct Sheet {
    #[garde(required)]
    remark: Option<String>,
    #[garde(length(min = 1))]
    rows: Vec<Row>,
    #[garde(nested)]
    header: Header,
}

#[derive(Validate)]
struct Row { #[garde(length(min = 1))} code: String }
#[derive(Validate)]
struct Header { title: String }

常见误区

  • 假设 None 自动跳过所有规则:是否跳过取决于规则与 required 标注,需对照文档确认。
  • 嵌套类型忘记递归标注:内层规则不执行,非法值流入业务层。

追问

  • 待确认:garde 对 Option 字段为空时规则执行的默认行为,验证方式为 garde 文档 Option 章节。
  • 集合为空是否违反规则?答:由集合长度规则决定;未标长度规则时空集合通过校验。

04.4.9.2-028 garde 校验错误如何映射成对外响应体?

一句话结论

错误转换层遍历 Report,按路径、code、params 与 message 组装字段错误数组,返回 422 与统一错误结构;内部类型不直接暴露给客户端。

概念解释

映射层职责:选择对外字段名(对应 Serde rename 后的契约名)、按 code 取本地化消息模板、组装路径数组。与 validator 错误响应的结构保持一致,前端只对接一套错误契约。报告中的触发值按需脱敏后再决定是否展示。

原理流程

  1. 服务层调用校验得到 Err(Report)。
  2. 遍历报告条目,读取路径与错误信息。
  3. code 映射消息模板,params 替换模板变量。
  4. 组装统一错误体,返回 422 状态码。

代码或图示

use serde::Serialize;

#[derive(Serialize)]
struct Issue { field: String, code: String, message: String }

fn report_to_issues(report: &garde::Report) -> Vec<Issue> {
    report.iter().map(|e| Issue {
        field: e.to_string(),
        code: "rule".into(),
        message: "invalid".into(),
    }).collect()
}

常见误区

  • 响应体直接序列化 Report 内部结构:字段名随版本变化,破坏契约稳定性。
  • 错误转换层夹杂业务判断:转换只做映射,规则结论以校验报告为准。

追问

  • 状态码用 422 还是 400?答:规则校验失败通常 422,结构解析失败另按提取器路径;项目约定需在错误分层文档中固定。
  • 多语言消息在哪一层生成?答:转换层根据请求语言选择模板,规则 code 与 params 是模板输入。

04.4.9.2-029 校验应放在 DTO 层还是领域层,两层如何分工?

一句话结论

DTO 层做输入形态校验(格式、长度、范围、必填),领域层做业务不变量校验(余额、状态机、聚合一致性);两层都保留,不能用 DTO 规则代替领域规则。

概念解释

DTO 规则回答「这个输入像不像合法的接口参数」,领域规则回答「这个操作在业务上是否成立」。邮箱格式合法不代表用户可以注册;参数长度合规不代表库存充足。领域校验在服务层操作聚合根时执行,失败属于业务错误,状态码与错误类型与输入校验分开。

原理流程

  1. 请求进入:DTO 层校验输入形态与格式规则。
  2. 构造领域模型,进入服务层用例。
  3. 领域层执行业务不变量检查,操作聚合状态。
  4. 两类失败分别映射不同错误结构与状态码。

代码或图示

DTO 层:email 格式、密码长度、手机号格式、字段必填
领域层:余额充足、库存可用、订单状态允许变更、权限匹配
服务层:唯一性、跨聚合规则、外部资源可用性

常见误区

  • 把业务规则写进 DTO 校验:领域规则依赖状态与上下文,字段级规则表达不了。
  • 领域模型不做任何自检,全部依赖接口层校验:绕过接口的其他调用方(任务、内部服务)失去保护。

追问

  • 哪些规则必须在领域层重复实现?答:跨字段、跨聚合、依赖持久化状态的规则,以及防止其他入口绕过接口校验的不变量。
  • 领域校验失败返回什么状态码?答:按业务错误类型映射,如 409 冲突、422 语义不合法、403 权限不足,具体在错误分层中定义。

04.4.9.2-030 依赖持久化状态的校验(唯一性、库存、重复提交)放在哪一层?

一句话结论

查库、查缓存、调用外部服务的规则放在服务层,不放在字段级校验函数中;DTO 规则只处理不依赖外部状态的纯判断。

概念解释

用户名唯一、库存充足、优惠券未使用这类规则需要访问存储或远程服务,执行有延迟与失败可能。字段级校验函数设计为快速纯判断,塞入 IO 会阻塞校验路径并引入事务边界问题。服务层在业务用例中执行这类规则,失败返回业务错误并配合并发控制。

原理流程

  1. DTO 形态校验通过后进入服务层。
  2. 服务层读取必要的持久化状态。
  3. 执行业务规则判断,必要时加锁或事务保护。
  4. 规则失败返回业务错误;通过后落库。

代码或图示

字段级规则:格式、长度、范围、编码模式
服务层规则:账号唯一性、库存余量、重复提交、权限归属

常见误区

  • 在 custom 规则函数里打开数据库连接:连接生命周期与校验路径脱节,难以管理。
  • 把唯一性检查当成防重唯一手段:并发下需唯一索引或分布式锁兜底,校验只做前置提示。

追问

  • 唯一性校验与数据库唯一索引如何配合?答:应用层预检提升体验,数据库索引保证最终一致性;冲突仍需捕获索引错误并返回业务提示。
  • 远程服务可用性校验放在哪?答:服务层调用并处理降级/超时,不在 DTO 校验路径内同步等待。

04.4.9.2-031 什么场景适合手写校验而不使用 derive 规则库?

一句话结论

规则高度依赖上下文、跨字段组合复杂、错误模型特殊,或项目不想引入校验库依赖时,可在 DTO 方法或服务层手写校验并返回自定义错误集合。

概念解释

derive 规则擅长单字段声明式校验;整体校验逻辑(跨字段、状态判断、分支规则)手写方法更直接。手写方案需要自行组织错误聚合、字段路径与响应映射,工作量大于声明式规则。小型项目或规则极少时,手写可以减少依赖。

原理流程

  1. 在 DTO 上定义 validate 类方法或在服务层写校验函数。
  2. 逐字段/跨字段执行判断,收集错误。
  3. 错误按字段路径聚合为自定义结构。
  4. 转换层映射为对外响应。

代码或图示

struct Form { start: String, end: String }

enum FormError { RangeInvalid, Required(String) }

impl Form {
    fn validate(&self) -> Result<(), Vec<FormError>> {
        let mut errs = Vec::new();
        if self.end <= self.start { errs.push(FormError::RangeInvalid); }
        if errs.is_empty() { Ok(()) } else { Err(errs) }
    }
}

常见误区

  • 手写校验只返回第一条错误:客户端需要多次提交才能修完所有问题,应聚合全部违反项。
  • 手写错误类型直接暴露给前端:内部枚举仍需经映射层转对外契约。

追问

  • 手写方案如何保持规则集中?答:校验函数放在 DTO 模块或校验工具模块,服务层统一调用,避免散落在各 handler。
  • 与 derive 库混合使用可以吗?答:可以,单字段规则用库,整体逻辑手写,错误在转换层合并。

04.4.9.2-032 跨字段校验(密码确认、起止时间)如何组织?

一句话结论

跨字段规则在整体校验方法或服务层执行:读取多个字段做比较,违反时把错误挂到相关字段路径;字段级规则函数访问不到兄弟字段。

概念解释

两次密码一致、结束时间晚于开始时间、数量不超过库存上限等规则涉及两个以上字段。字段级 custom 只收到当前字段值,无法比较兄弟字段。常见做法:在 DTO 的整体校验方法中比较,或在服务层用领域模型判断,错误路径指向主字段或关联字段。

原理流程

  1. 单字段规则先执行,格式合法性已确认。
  2. 整体校验方法读取多个字段值做比较。
  3. 违反规则构造错误并挂到对应路径。
  4. 聚合后统一返回响应。

代码或图示

struct PasswordForm { password: String, confirm: String }

impl PasswordForm {
    fn validate_match(&self) -> Result<(), String> {
        if self.password != self.confirm {
            Err("两次密码不一致".into())
        } else { Ok(()) }
    }
}

常见误区

  • 把跨字段比较塞进单字段 custom:函数拿不到兄弟字段,只能绕路读全局状态。
  • 错误只挂一个字段:关联字段都应在响应中提示,便于前端修正。

追问

  • 跨字段规则需要上下文数据时放哪?答:服务层用领域模型与上下文判断;DTO 整体方法只适合不依赖外部状态的比较。
  • 时间区间校验要考虑时区吗?答:内部统一 UTC 比较,输入解析时完成时区归一化,避免本地时区错位。

04.4.9.2-033 校验错误信息如何支持国际化(i18n)?

一句话结论

响应携带规则 code 与参数,消息模板按请求语言选择;错误文案外置到资源文件,代码中不硬编码面向用户的多语言文案。

概念解释

错误条目里的 code 是稳定标识,params 提供边界值等模板变量;国际化层根据 Accept-Language 或用户语言偏好选择模板,把参数填入占位符。代码只产出 code 与参数,不直接生成最终文案。新增语言不需要改动校验规则代码。

原理流程

  1. 校验规则违反时记录 code 与 params。
  2. 错误转换层确定当前请求语言。
  3. 按 code 查资源模板,替换 params 变量。
  4. 组装多语言消息写入响应体。

代码或图示

code: "length"
params: { "min": 3, "max": 32 }
模板(zh):长度需在 {min} 到 {max} 之间
模板(en):Length must be between {min} and {max}

常见误区

  • 在校验库里直接写死中文消息:无法按语言切换,也不利于前端覆盖文案。
  • 消息模板不随 params 更新:规则边界调整后旧文案与实际约束不一致。

追问

  • 语言偏好从哪里读取?答:Accept-Language 头或用户资料中的语言设置,按项目约定优先级解析。
  • 模板缺失兜底怎么办?答:回退到默认语言或 code 本身,并在日志记录缺失模板。

04.4.9.2-034 校验错误的错误码如何设计?

一句话结论

错误码分层稳定:大类标识错误来源(参数校验/业务冲突/认证),细码标识具体规则或场景;机器可读 code 与人类可读 message 并存,code 一旦对外不再随意改动。

概念解释

错误码服务于前端分支处理、监控统计与国际化映射。设计上区分 HTTP 状态码(传输层语义)与业务错误码(应用层场景)。规则 code 可复用内置规则名,业务错误码按模块与场景编号。响应体同时给出 code、message 与字段级细节。

原理流程

  1. 定义错误码大类与命名规范。
  2. 校验失败映射规则 code,业务失败映射场景码。
  3. 响应体携带 code、message 与 issues 数组。
  4. 监控按 code 聚合错误频率,发现高频输入问题。

代码或图示

{
  "code": "validation_failed",
  "message": "参数校验未通过",
  "issues": [
    { "field": "email", "code": "email", "message": "邮箱格式不正确" }
  ]
}

常见误区

  • 错误码只对应 HTTP 状态码:422 下多种场景无法区分,前端与监控都缺少粒度。
  • 对外 code 频繁改名:客户端已依赖旧码,变更属于 breaking change,需版本化过渡。

追问

  • 错误码需要全局唯一吗?答:模块内唯一即可,响应携带模块前缀或按作用域分组;全局清单在契约文档中维护。
  • 内置规则 code 直接对外暴露是否合适?答:可暴露稳定规则名,项目也可在转换层映射为业务码,二者选择其一并统一。

04.4.9.2-035 校验规则的性能如何考虑,正则与重复校验有哪些注意点?

一句话结论

校验成本集中在正则编译、长字符串遍历与集合逐个检查;热路径上应复用编译后的正则、避免不必要的重复校验,并以基准测量定位瓶颈。

概念解释

单条规则成本很低,但高并发下累积可观。正则表达式每次使用重复解析会浪费 CPU;超长字符串做长度与格式扫描需要边界控制;大列表逐个元素校验放大整体耗时。校验位置也要避免同一请求重复执行同一规则。

原理流程

  1. 基准测量校验在请求链路中的耗时占比。
  2. 正则等昂贵资源确认是否缓存复用。
  3. 长度/大小限制在框架层兜底,规则层聚焦语义判断。
  4. 避免在中间件、handler、服务层重复跑同一套规则。

代码或图示

性能关注点:
- 正则编译时机与缓存
- 长字符串/大集合的规则遍历成本
- 同一请求内校验执行次数
- 校验路径上是否混入 IO 调用

常见误区

  • 在高频接口里做未受限的正则回溯:恶意输入可放大 CPU 占用,模式需评审复杂度。
  • 凭感觉优化:先测量确认校验是否真的是瓶颈,再调整规则实现。

追问

  • 大文件/大文本字段在哪里限制大小?答:请求 body 大小限制在框架/中间件层,字段长度规则在 DTO 层补充语义边界。
  • 校验能异步化吗?答:输入合法性必须在响应前同步完成,异步化只适合后置审计与统计,不能替代前置校验。

04.4.9.2-036 校验失败与业务规则失败在状态码和错误结构上如何分层?

一句话结论

输入形态校验失败归为参数错误(通常 422/400),业务不变量失败归为业务错误(409/422/403 等按场景);两类错误使用不同结构与错误码,不混在同一字段列表里。

概念解释

参数校验问题客户端可通过修改输入解决;业务失败如冲突、超限、权限不足,需要不同处理动作。状态码选择遵循语义:冲突用 409,语义不合法用 422,拒绝授权用 403。错误结构区分 issues 字段级列表与业务错误主体,前端按类型分支提示。

原理流程

  1. DTO 校验失败:返回字段级 issues,状态码按参数错误约定。
  2. 服务层业务规则失败:返回业务错误码与消息。
  3. 领域异常经错误转换层映射为统一响应。
  4. 两类错误在日志中分别归类统计。

代码或图示

参数错误:422 + issues 字段数组,规则 code 为主
业务冲突:409 + 业务错误码,如 stock_conflict
权限拒绝:403 + 权限错误码
系统异常:500 + 请求 ID,不暴露内部细节

常见误区

  • 所有失败都返回 422:业务冲突与权限问题被前端当成输入错误处理。
  • 业务错误也塞字段 issues 数组:结构混淆,前端无法区分修复方向。

追问

  • 待确认:项目现有错误分层约定中各状态码的使用边界,验证方式为项目错误处理章节与已有 handler 实现。
  • 校验通过但业务拒绝时是否还要返回字段细节?答:业务错误按场景返回资源标识与原因,不强制字段路径结构。

04.4.9.2-037 PATCH 部分更新接口如何处理可选字段的校验?

一句话结论

PATCH 字段用 Option 表达「未提供」,只对提供了值的字段执行规则;三态区分(未传/null/有值)需要在反序列化阶段保留原始信息,避免把未提供误判为空值。

概念解释

部分更新允许客户端只提交要改的字段:未传字段保持原值,传了值才校验与更新。直接用普通可选类型会把缺键与 null 合并到 None,无法区分「不改」与「清空」。字段级规则应跳过 None,有值时再检查长度、格式等规则。

原理流程

  1. 请求 DTO 字段声明为可选包装类型。
  2. 反序列化阶段保留缺键与 null 的区分(必要时先读 Value)。
  3. 校验只对 Some 提供的值执行规则。
  4. 服务层按三态决定保留、清空或更新为新值。

代码或图示

use serde::Deserialize;

#[derive(Deserialize)]
struct UpdateProfile {
    nickname: Option<String>,
    bio: Option<Option<String>>,
}

常见误区

  • 未提供字段被更新为空串/None:覆盖了数据库原值,属于数据事故。
  • 对 None 也执行必填/长度规则:未提供字段不应报错。

追问

  • Option<Option<T>> 表达什么?答:外层表示是否提供,内层表示值是否为空,用于区分不改、清空、设为新值。
  • PATCH 校验规则与创建接口复用吗?答:单字段规则可复用,必填与跨字段规则按用例分别配置。

04.4.9.2-038 校验规则的测试用例如何组织?

一句话结论

按规则维度准备合法、非法与边界值样例,断言字段路径、规则 code 与错误数量;嵌套与集合场景覆盖索引路径,跨字段规则覆盖比较两侧。

概念解释

测试固定规则行为,防止依赖升级或规则调整破坏校验。用例分三类:合法输入通过、非法输入返回预期错误、边界值(最小/最大/越界)行为正确。错误断言聚焦字段路径与 code,不依赖模糊的消息文案。

原理流程

  1. 为每个 DTO 编写校验测试模块。
  2. 准备合法样例与各规则非法样例。
  3. 调用校验方法,断言 Ok 或 Err 中的错误路径与 code。
  4. 嵌套/集合样例覆盖完整路径形式。

代码或图示

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rejects_short_name() {
        let form = Form { name: "a".into() };
        let errs = form.validate().unwrap_err();
        assert!(errs.errors().contains_key("name"));
    }
}

常见误区

  • 只测合法路径:非法输入被放过是校验库最常见的漏测。
  • 断言完整错误消息:文案随 i18n 调整,应断言 code 与路径。

追问

  • 边界值如何取值?答:规则的 min/max 各测一次合法值与相邻越界值,集合测空、下限、上限、超上限。
  • 跨字段规则测试要准备哪些组合?答:相等、前者大、后者大、空值与类型边界,覆盖比较分支。

04.4.9.2-039 OpenAPI 契约在 Rust 后端中解决什么问题,生成方式分哪几类?

一句话结论

OpenAPI 用机器可读文档描述接口路径、参数、请求体、响应与错误结构;生成方式分三类:从 Rust 类型与 handler 派生(如 utoipa/aide)、手写或半自动维护 spec 文件、由代码注解生成。

概念解释

契约服务于前后端协作、Mock 生成、SDK 生成与接口评审。派生方式让文档与实现同源,降低漂移风险;手写 spec 灵活但容易过期。Rust 生态主流是从类型系统派生 schema,handler 注解补充路径与响应描述。

原理流程

  1. 定义请求/响应 DTO 并实现 schema 派生 trait。
  2. 在 handler 或路由上声明路径、参数与响应映射。
  3. 组装 OpenApi 结构,输出 JSON 文档。
  4. 文档页面或代码生成器消费 spec。

代码或图示

派生式:Rust 类型 + handler 注解 → OpenAPI JSON
手写式:维护 openapi.yaml/json,与代码分别演进
注解式:源码注释/属性抽取元信息生成文档

常见误区

  • 文档与代码各写一套:字段演进时两边不同步,契约失真。
  • 把 OpenAPI 当成给人看的静态页面:它同时是 SDK/Mock/测试工具的输入。

追问

  • OpenAPI 与 Serde 类型是什么关系?答:schema 描述对外契约形态,DTO 的 Serde 命名/可选属性会反映到 schema 生成中,具体映射以文档库行为为准。
  • 待确认:Rust 生态当前主流 OpenAPI 库的维护状态,验证方式为 crates.io 与 docs.rs 对比。

04.4.9.2-040 utoipa 在 Rust 生态中如何定位?

一句话结论

utoipa 是从 Rust 类型派生 OpenAPI 文档的 crate:DTO 实现 ToSchema,handler 经 #[utoipa::path] 声明接口,组装 OpenApi 结构后输出 spec 并挂载 Swagger UI。

概念解释

utoipa 把类型系统作为 schema 来源:结构体、枚举、Option、Vec 等映射为 OpenAPI schema;路径与响应通过过程宏登记。它与 Web 框架松耦合,通过集成方式与 axum 等框架配合(具体集成 crate 与 feature 以当前版本为准)。

原理流程

  1. DTO derive ToSchema 并配合 Serde 类型。
  2. handler 标注路径宏,声明参数、请求体与响应。
  3. 汇总路径与组件 schema 构造 OpenApi。
  4. 暴露 openapi.json 并挂载 Swagger UI 页面。

代码或图示

[dependencies]
utoipa = "*"
# Swagger UI 与框架集成组件按当前文档选择(待确认)

常见误区

  • 以为 utoipa 自动读取路由表:路径注册仍需在宏或 OpenApi 组件中显式声明。
  • 忽略版本集成细节:框架版本与 utoipa 集成方式需对照当前文档核对。

追问

  • 待确认:utoipa 当前版本号、axum 集成方式与 swagger-ui 组件 crate 名,验证方式为 docs.rs/utoipa。
  • utoipa 支持哪些数据类型映射?答:基础标量、字符串、数值、布尔、Option、Vec、嵌套结构体与枚举,具体推导边界以文档为准。

04.4.9.2-041 ToSchema derive 如何把结构体映射为 OpenAPI schema?

一句话结论

#[derive(ToSchema)] 为结构体生成 schema 实现:字段名、类型、可选性与嵌套关系映射为 OpenAPI 对象 schema,字段级 #[schema(...)] 可补充示例、描述与重命名。

概念解释

ToSchema 是 utoipa 的 schema 派生 trait,角色类似 Serde 的 Serialize。派生读取字段类型生成属性集合:对象类型声明字段列表,Option 标记可选,Vec 映射为数组类型。schema 组件在 OpenApi 中注册后可被响应/参数引用。

原理流程

  1. 结构体标注 #[derive(ToSchema)]。
  2. 派生遍历字段类型生成 schema 属性。
  3. 字段属性补充 example、description 等元信息。
  4. schema 注册进 components,路径响应按名称引用。

代码或图示

use utoipa::ToSchema;
use serde::Serialize;

#[derive(Serialize, ToSchema)]
struct UserResponse {
    /// 用户 ID
    id: u64,
    /// 昵称
    name: String,
}

常见误区

  • 字段类型在 ToSchema 与 Serde 之间不一致:对外契约形态分裂,DTO 应保持两套派生基于同一字段定义。
  • schema 不注册进组件:响应引用不到,文档中字段类型丢失。

追问

  • 文档注释如何进入 schema?答:doc 注释通常映射为字段描述,具体行为以 utoipa 当前版本文档为准。
  • 嵌套结构体需要单独 derive 吗?答:需要,嵌套类型自身实现 ToSchema 后才能被外层引用。

04.4.9.2-042 ToSchema 如何推导 Option、Vec、嵌套与枚举类型?

一句话结论

Option<T> 映射为可选字段并可标注 nullable,Vec<T> 映射为数组项类型为 T 的数组;嵌套结构体引用其 schema,枚举映射为变体联合(oneOf/枚举值形式按库实现)。

概念解释

类型推导规则对应 OpenAPI 数据模型:标量直接映射类型名,集合映射 type: array,可空字段标记 optional/nullable,复合结构引用组件 schema。枚举单元变体常映射为字符串枚举值,带数据变体的映射方式更复杂,需在生成文档中核对。

原理流程

  1. 派生识别字段外层类型:Option/Vec/普通结构。
  2. 剥离外层后取内层类型继续推导。
  3. 复合类型生成引用或联合 schema。
  4. 枚举按变体形态生成值集合或嵌套联合。

代码或图示

use utoipa::ToSchema;

#[derive(ToSchema)]
struct ListResp {
    total: u64,
    items: Vec<Item>,
    keyword: Option<String>,
}

#[derive(ToSchema)]
struct Item { sku: String, qty: u32 }

#[derive(ToSchema)]
enum Color { Red, Green, Blue }

常见误区

  • 以为 Option<String> 在 schema 里一定显式 nullable:可选与可空的表达形式取决于库版本与 OpenAPI 版本,需在生成文档中确认。
  • 复杂枚举变体未出现在文档:应检查派生支持范围,必要时手写 schema 覆盖。

追问

  • 待确认:utoipa 当前版本对枚举变体、nullable 与 oneOf 的具体映射形式,验证方式为 docs.rs/utoipa 示例与生成的 openapi.json。
  • 自定义新类型如何出现在 schema 中?答:derive ToSchema 或用 schema 属性声明其底层类型映射。

04.4.9.2-043 #[schema(...)] 字段属性可以补充哪些文档元信息?

一句话结论

字段级 schema 属性可补充示例值、描述、重命名、可空标记与类型覆盖等元信息,用于修正派生结果与丰富文档展示。

概念解释

类型推导给出基础 schema,业务语义常需要补充:示例值方便 Mock 与调试,描述说明字段用途,重命名对齐对外契约名。属性名与可选项属于版本敏感信息,使用前核对 utoipa 当前文档。派生结果不足以表达时,可在类型或字段级别做覆盖。

原理流程

  1. 派生生成基础字段 schema。
  2. #[schema(...)] 属性覆盖或补充元信息。
  3. 示例、描述写入 schema 组件。
  4. 生成文档时在字段说明与示例中展示。

代码或图示

use utoipa::ToSchema;

#[derive(ToSchema)]
struct Profile {
    #[schema(example = "ann", description = "用户昵称")]
    nickname: String,
    #[schema(rename = "userAge")]
    age: u8,
}

常见误区

  • 示例值与校验规则冲突:example 应满足长度、范围等约束,避免文档误导。
  • 在 schema 属性里改业务类型:类型变更属于契约修改,不应只靠文档属性掩盖。

追问

  • 待确认:当前版本 schema 属性支持的完整参数清单(example/rename/description/nullable/type 等),验证方式为 docs.rs/utoipa schema 章节。
  • 结构体级别能否覆盖 schema?答:可以在类型级别标注 schema 属性或手写实现,具体覆盖范围以文档为准。

04.4.9.2-044 OpenApi 结构体如何组织路径与组件 schema?

一句话结论

OpenApi 聚合路径定义与可复用 schema 组件:路径列表登记每个接口的操作描述,components 注册 DTO 生成的 schema,响应与参数按名称引用组件。

概念解释

OpenAPI 文档分两部分:操作层(路径、方法、参数、响应)与定义层(可复用数据结构)。utoipa 的 OpenApi 结构把两者汇总,schema 组件避免重复定义同一 DTO。组装通常在应用启动期完成,输出为 JSON 文档。

原理流程

  1. 收集各 handler 的路径宏定义。
  2. 注册请求/响应 DTO 的 ToSchema 组件。
  3. 构造 OpenApi,填入标题、版本、路径与组件。
  4. 序列化输出 openapi.json 供文档页面与工具消费。

代码或图示

use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(
    paths(crate::handlers::list, crate::handlers::create),
    components(schemas(crate::dto::UserResponse, crate::dto::CreateUser))
)]
struct ApiDoc;

常见误区

  • 响应引用了未注册的 schema 组件:文档中该结构丢失或显示为空对象。
  • 路径只在 Web 路由表注册而未进 OpenApi:Swagger 页面看不到该接口。

追问

  • schema 组件按什么命名?答:默认按类型名注册,具体命名规则与重命名方式以当前文档为准。
  • 大型项目如何拆分 OpenApi 组装?答:按模块分拆路径与组件列表,在根 OpenApi 结构中汇总合并。

04.4.9.2-045 #[utoipa::path(...)] 宏可以声明哪些接口信息?

一句话结论

路径宏挂在 handler 上,声明 HTTP 方法、路径模板、参数、请求体、响应状态码与对应 schema、标签与摘要等元信息。

概念解释

handler 函数签名提供类型信息,路径宏补充文档层面的描述:方法与 URL 模板、路径/查询/头参数、请求体类型、各状态码响应。宏参数按 OpenAPI 结构组织,未声明的响应不会出现在文档中。

原理流程

  1. handler 函数标注 #[utoipa::path]。
  2. 宏内填写方法、路径、params、request_body、responses。
  3. 路径定义被收集进 OpenApi 的 paths。
  4. 响应 schema 引用 components 中注册的 DTO。

代码或图示

use utoipa::path;
use axum::Json;

#[utoipa::path(
    get,
    path = "/users/{id}",
    params(("id" = u64, description = "用户 ID")),
    responses((status = 200, body = UserResponse), (status = 404, body = ErrorBody))
)]
async fn get_user(Json(_): Json<()>) -> Json<UserResponse> { todo!() }

常见误区

  • 只写 200 响应不写错误响应:文档遗漏 4xx/5xx,前端按成功结构对接。
  • 路径模板与实际 Web 路由不一致:文档与实现漂移,测试应比对两边路径。

追问

  • 待确认:当前版本 path 宏参数名(params/request_body/responses/tag/summary 等)写法,验证方式为 docs.rs/utoipa path 示例。
  • 宏里的类型引用需要满足什么 trait?答:请求/响应类型需实现 utoipa 的 schema 派生 trait,具体约束以文档为准。

04.4.9.2-046 path![] 宏与 schema 组件注册如何配合?

一句话结论

path![] 宏在代码中收集路径定义,组件列表在 OpenApi 的 components 中登记;两者共同构成完整 spec,响应体类型必须在组件列表可解析到。

概念解释

除了直接在 handler 上挂路径宏,项目也可在文档模块用 path![] 汇总操作定义。schema 组件通过 schemas(...) 列表注册,路径响应引用这些组件名。注册顺序与分组按模块组织,避免大型文档遗漏 DTO。

原理流程

  1. 各 handler 路径定义通过宏或 path![] 汇总。
  2. OpenApi components 列出全部复用 DTO。
  3. 生成时路径解析引用到组件 schema。
  4. 未注册类型在文档中暴露为缺失,需补进组件列表。

代码或图示

use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(
    paths(utoipa::path!(/* 汇总引用 */)),
    components(schemas(UserResponse, ErrorBody))
)]
struct Doc;

常见误区

  • 响应类型写在宏里却没进 components:文档解析不到 schema 定义。
  • 模块拆分后忘记把新 DTO 加入组件列表:新接口文档字段为空。

追问

  • 待确认:当前版本 path![] 宏的用途与语法细节,验证方式为 utoipa 文档与示例工程。
  • 组件可以跨模块复用吗?答:可以,DTO 只注册一次,多个路径响应引用同一组件。

04.4.9.2-047 utoipa 如何与 axum 路由组装到同一应用?

一句话结论

Web 路由表负责实际请求分发,utoipa 文档结构负责生成 spec;两者在应用构造期分别组装,文档接口(openapi.json 与 Swagger UI)作为普通路由挂载到同一 Router。

概念解释

utoipa 不替代框架路由,而是从类型与宏生成文档模型。axum 应用先按业务注册 handler 路由,再挂载文档 JSON 端点与 UI 路由。handler 上的路径宏需与路由模板保持一致,否则文档与实现漂移。

原理流程

  1. 业务 Router 注册各 handler 路由。
  2. 构造 OpenApi 实例,汇总路径与组件。
  3. 文档 JSON 端点返回 OpenApi 序列化结果。
  4. Swagger UI 路由引用 JSON 端点地址,合并进同一 Router 启动服务。

代码或图示

use axum::Router;
use utoipa::OpenApi;

let app = Router::new()
    .route("/users", axum::routing::get(list))
    .route("/api-docs/openapi.json",
        axum::routing::get(|| async { axum::Json(ApiDoc::openapi()) }));

常见误区

  • 以为注册 axum 路由后 utoipa 自动发现:路径仍需在宏/OpenApi 中显式声明。
  • 文档路由挂在鉴权中间件之外或之内不明确:内部接口文档应按安全要求控制访问。

追问

  • 待确认:utoipa 与当前 axum 版本的集成 crate/feature 名称,验证方式为 docs.rs/utoipa 集成章节与示例工程。
  • 路由模板改了先改哪里?答:先改 Web 路由与 handler 路径宏两处,再生成文档比对,避免单边修改。

04.4.9.2-048 Swagger UI 如何挂载,openapi.json 端点如何暴露?

一句话结论

通过 swagger-ui 集成组件挂载 UI 路由,UI 配置指向 openapi.json 端点;JSON 端点返回序列化的 OpenApi 结构,两个端点都注册到应用 Router。

概念解释

Swagger UI 是渲染 spec 的页面,本身不生成 schema。应用提供两个端点:JSON spec 地址供 UI 与代码生成器消费,UI 地址供浏览器访问。UI 组件 crate 与版本按 utoipa 当前文档选择,路由路径可按项目前缀调整。

原理流程

  1. 构造 OpenApi 实例并序列化为 JSON。
  2. 注册 JSON 端点返回 spec。
  3. 挂载 Swagger UI,传入 UI 路径与 JSON 端点 URL。
  4. 浏览器访问 UI 路径加载并渲染接口文档。

代码或图示

// 组件名与挂载 API 待确认,以 docs.rs/utoipa-swagger-ui 当前版本为准
use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(info(title = "Demo API", version = "1.0.0"))]
struct ApiDoc;

// 示例路由形态;具体 SwaggerUi 构造按集成组件文档
async fn openapi_json() -> impl axum::IntoResponse {
    axum::Json(ApiDoc::openapi())
}

常见误区

  • UI 路由与 JSON 端点地址配置不一致:页面加载不到 spec。
  • 生产环境公开内部文档而不加访问控制:文档暴露接口结构,需按安全策略鉴权。

追问

  • 待确认:当前版本 swagger-ui 组件 crate 名、路由路径占位语法与挂载方法,验证方式为 docs.rs 对应组件文档。
  • 除 Swagger UI 外还能消费 spec 吗?答:可以,openapi.json 可导入 Postman、生成 SDK 与契约测试工具。

04.4.9.2-049 如何在文档中声明多种状态码响应及其 schema?

一句话结论

路径宏的 responses 按状态码分组,每组绑定响应体类型与描述;成功响应与各类错误响应分别登记,前端才能拿到完整的可能返回结构。

概念解释

一个接口可能返回 200、400、404、422、500 等多种结果。文档逐一声明状态码与 body schema,未声明的响应不出现在 spec 中。错误响应建议复用统一错误体 DTO,避免每个接口各写一套结构描述。

原理流程

  1. 梳理 handler 可能返回的全部状态码。
  2. 宏内 responses 逐一声明状态码、body 类型与说明。
  3. 错误体 DTO 注册为共享组件。
  4. 生成文档后检查每个状态码都有对应 schema。

代码或图示

#[utoipa::path(
    get,
    path = "/orders/{id}",
    responses(
        (status = 200, description = "订单详情", body = OrderResponse),
        (status = 404, description = "订单不存在", body = ErrorBody),
        (status = 422, description = "参数校验失败", body = ValidationErrorBody)
    )
)]

常见误区

  • 只登记成功响应:错误结构在文档中缺失,前端按 200 结构处理异常。
  • 错误响应各接口手写不同结构描述:应复用统一错误 DTO,保持契约一致。

追问

  • 响应没有 body(204)如何声明?答:按文档约定声明空响应或不绑定 body 类型,具体写法以 utoipa 版本为准(待确认)。
  • 响应 schema 可以是集合或包装结构吗?答:可以,DTO 本身表达包装/列表形态,ToSchema 推导对应结构。

04.4.9.2-050 路径、查询、头参数与请求体分别如何注册到文档?

一句话结论

路径参数在 params 中声明名称与类型,查询/头参数同理描述;请求体通过 request_body 绑定 DTO 类型;参数类型与提取器实际使用的类型保持一致。

概念解释

OpenAPI 参数按位置区分:path 段、query 串、header、cookie,body 单独描述。utoipa 从宏声明与 DTO 类型生成参数 schema。文档参数名必须与 Web 路由模板、提取器字段名一致,否则前端传参对不上。

原理流程

  1. 路径模板中的占位段在 params 中登记类型与描述。
  2. 查询参数按 DTO 字段或宏声明映射。
  3. 请求体绑定 request_body DTO。
  4. 头参数按名称与类型登记,安全相关头可单独说明。

代码或图示

#[utoipa::path(
    get,
    path = "/items",
    params(
        ("page" = u32, Query, description = "页码"),
        ("size" = u32, Query, description = "每页条数")
    ),
    responses((status = 200, body = ListResp))
)]

常见误区

  • 文档参数名与提取器字段名不一致:客户端按文档传参,实际提取不到。
  • 可选查询参数未标记可选:文档把可选参数描述为必填。

追问

  • 待确认:当前版本参数位置标记(Query/Header/Path/Cookie)的宏写法,验证方式为 utoipa 参数文档。
  • 复杂查询对象如何文档化?答:用 DTO 描述字段集合,或按参数逐个声明,两种方式与框架提取器选择保持一致。

04.4.9.2-051 枚举类型在 OpenAPI 文档中如何表达?

一句话结论

单元变体枚举通常映射为字符串枚举值集合;带数据变体按联合结构表达,具体形式由 ToSchema 派生实现决定,需在生成的 spec 中核对。

概念解释

OpenAPI 对枚举的表达:简单枚举列出允许值,复杂变体用 oneOf 等联合结构。Rust 枚举的标签策略(外部/内部/相邻/untagged)会影响 JSON 形态,schema 文档应与实际序列化形态一致。枚举新增变体属于契约变更,需评估客户端兼容。

原理流程

  1. 枚举 derive ToSchema。
  2. 派生按变体类型生成值集合或联合 schema。
  3. schema 注册进组件供响应/参数引用。
  4. 核对生成的枚举值与 Serde 标签输出一致。

代码或图示

use utoipa::ToSchema;
use serde::Serialize;

#[derive(Serialize, ToSchema)]
enum OrderStatus { Pending, Paid, Shipped }

常见误区

  • schema 枚举值与 Serde rename 后的值不一致:文档与实际响应脱节,两边需同步。
  • 带数据变体直接假设文档可读:复杂变体可能需要手写 schema 补充结构。

追问

  • 待确认:utoipa 当前版本对结构体变体、元组变体的 schema 生成方式,验证方式为生成的 openapi.json 与示例。
  • 枚举未知值如何在文档说明?答:在描述中标注兼容策略,新增变体的版本节奏写入契约说明。

04.4.9.2-052 错误响应结构如何纳入 OpenAPI 文档?

一句话结论

定义统一错误体 DTO 并 derive ToSchema,在各接口 responses 的 4xx/5xx 状态码上引用;字段级校验错误也用专用 DTO 描述 issues 数组。

概念解释

错误响应是契约的一部分:错误码、消息、字段路径与参数都应可被前端与工具理解。复用同一错误 DTO 避免文档重复且保证结构一致。校验错误体单独建模:字段路径、规则 code、消息列表。

原理流程

  1. 定义错误响应 DTO(code/message/issues)。
  2. derive ToSchema 并注册组件。
  3. 接口宏在错误状态码上绑定该 DTO。
  4. 生成 spec 后检查错误结构与实际 IntoResponse 输出一致。

代码或图示

use utoipa::ToSchema;
use serde::Serialize;

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

#[derive(Serialize, ToSchema)]
struct ValidationIssue {
    field: String,
    code: String,
    message: String,
}

常见误区

  • 错误响应不写进文档:前端只能猜异常结构,Mock 也无法生成错误样例。
  • 文档错误结构与实际响应字段名不一致:以实际 IntoResponse 实现为准反查 schema。

追问

  • 500 错误是否也写进文档?答:可在通用错误说明中登记,内部堆栈不暴露给客户端。
  • 待确认:utoipa 对嵌套数组结构 issues 的 schema 推导表现,验证方式为生成的 spec 字段类型。

04.4.9.2-053 ToSchema 派生如何与 Serde 属性配合?

一句话结论

同一 DTO 同时 derive Serde 与 ToSchema,字段命名、可选性等约定应保持一致;Serde 的 rename/skip/flatten 是否反映到 schema 取决于文档库实现,需在 spec 中核对。

概念解释

对外契约由序列化形态与 schema 描述共同定义:JSON 实际输出按 Serde 属性,文档结构按 ToSchema 推导。两边对字段名、可空性、嵌套层级的表达必须一致。派生库通常读取类型字段定义,但复杂 Serde 属性(flatten、自定义 with)不一定完整映射。

原理流程

  1. DTO 同时标注 Serde 与 ToSchema derive。
  2. 字段命名与可选性在类型层面统一。
  3. 生成 spec 后对照实际 JSON 样例检查字段名与层级。
  4. 不一致处用 schema 属性补充或手写 schema 修正。

代码或图示

use serde::Serialize;
use utoipa::ToSchema;

#[derive(Serialize, ToSchema)]
struct ApiItem {
    #[serde(rename = "itemId")]
    #[schema(rename = "itemId")]
    id: u64,
}

常见误区

  • 只在 Serde 侧改名,schema 侧仍用 Rust 原名:文档键名与实际响应不一致。
  • flatten 字段假设文档自动拍平:需核对 ToSchema 是否识别 flatten 语义。

追问

  • 待确认:utoipa 当前版本识别哪些 Serde 属性(rename/skip/flatten/with),验证方式为 utoipa 文档与生成 spec 对比。
  • 两套派生冲突时以谁为准?答:以实际序列化输出为准,schema 向实际契约对齐并补文档属性。

04.4.9.2-054 派生 schema 不足以表达时,如何手写覆盖?

一句话结论

可以为类型手写 utoipa schema trait 实现,或在属性中声明类型/示例覆盖派生结果;用于复杂联合结构、外部类型包装与特殊格式描述。

概念解释

自动推导覆盖常见结构体与集合,特殊场景需要人工定义:自定义编解码格式、枚举联合、需要固定示例与约束的字段。手写实现保持类型与 schema 同步,覆盖后仍应在生成 spec 中核对结构。

原理流程

  1. 检查派生结果与目标契约的差异点。
  2. 优先用字段级 schema 属性修正。
  3. 差异复杂时手写 schema trait 实现,按 OpenAPI 结构定义类型。
  4. 回归生成文档,确认覆盖生效且未影响其他组件。

代码或图示

// 手写实现方式待确认,以 docs.rs/utoipa 当前版本 schema 自定义章节为准
// 思路:实现 ToSchema 对应 trait,构造对象 schema 并填充字段

常见误区

  • 派生不符就绕过文档手写 spec 文件:又回到文档与代码分离维护的漂移问题。
  • 手写 schema 后不随 DTO 演进更新:人工定义成为新的过期点。

追问

  • 待确认:当前版本自定义 schema 的 trait 名与构造 API,验证方式为 utoipa 高级用法文档。
  • 外部 crate 类型无法 derive 时怎么办?答:用项目内新类型包装,为包装类型实现 schema 与 Serde 适配。

04.4.9.2-055 utoipa 的 feature 与框架集成特性如何核对?

一句话结论

crate 分核心 schema/OpenApi 生成与框架集成、UI 挂载等附加组件;feature 名与集成 crate 属于版本敏感信息,使用前以 docs.rs 当前文档为准并标注待确认点。

概念解释

核心依赖提供 ToSchema/OpenApi/路径宏;与 axum 等框架的路由配合、Swagger UI 页面通常由独立组件或 feature 提供。不同框架集成方式不同,项目升级 utoipa 时需回归文档生成与挂载路由。

原理流程

  1. 查看 utoipa 文档的 feature 与集成章节。
  2. 按框架选择对应集成组件与版本。
  3. 最小示例跑通:生成 spec、挂载 UI、响应可访问。
  4. 项目锁定版本后记录集成方式基线。

代码或图示

待确认核对项:
- utoipa 核心 feature 清单
- axum/其他框架集成组件 crate 名
- swagger-ui 组件版本兼容关系
验证方式:docs.rs/utoipa、docs.rs/utoipa-swagger-ui 与示例工程

常见误区

  • 照搬旧版本教程的集成写法:版本演进后组件拆分或 API 更名,旧代码可能编译不过。
  • 不核对兼容矩阵就升级:框架与文档库版本错位会导致集成层编译失败。

追问

  • 待确认:utoipa 与 axum 当前推荐版本组合,验证方式为 utoipa 文档兼容说明与 cargo 依赖解析结果。
  • 集成组件缺失时的降级方案?答:先独立输出 openapi.json,UI 用外部工具导入,不阻塞业务接口上线。

04.4.9.2-056 如何用标签(tag)对接口分组组织文档?

一句话结论

路径宏与 OpenApi 元信息中为接口打标签,Swagger UI 按标签分组展示;标签定义可在文档元信息中集中维护,对应业务模块。

概念解释

大型服务接口众多,标签把接口按模块(用户、订单、支付)归类,便于浏览与检索。标签可带描述说明,路径通过 tag 归属分组。标签命名应与路由模块、代码组织保持一致,避免分组散乱。

原理流程

  1. 按业务模块确定标签集合。
  2. 路径宏中为每个接口标注 tag。
  3. OpenApi 元信息可补充标签描述。
  4. 文档页面按标签折叠分组展示。

代码或图示

#[utoipa::path(
    get,
    path = "/users",
    tag = "用户管理",
    responses((status = 200, body = UserList))
)]

常见误区

  • 接口不加标签全部散落根目录:文档浏览成本随接口数量上升。
  • 同一模块标签命名前后不一致:页面出现重复分组。

追问

  • 待确认:当前版本标签在 OpenApi 级别定义与路径级标注的写法,验证方式为 utoipa 文档 tags 章节。
  • 标签能否用于权限分组?答:标签主要服务文档组织,接口鉴权仍由框架中间件与权限层控制。

04.4.9.2-057 文档元信息(标题、版本、联系人、许可证)如何配置?

一句话结论

OpenApi 元信息包含文档标题、API 版本、描述、联系人与许可证等;在 OpenApi 结构的 info 部分集中声明,随接口版本演进更新。

概念解释

元信息描述服务整体身份与联系渠道,是契约文档的头部内容。API 版本号应与路由版本、发布节奏对应;联系人信息便于消费方对接问题。元信息不替代各接口的描述说明。

原理流程

  1. 在 OpenApi 注解中填写 title、version、description。
  2. 按需补充联系人、许可证、服务端地址。
  3. 生成 spec 后检查 info 字段完整。
  4. 接口大版本升级时同步更新文档版本号。

代码或图示

use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(
    info(
        title = "订单服务 API",
        version = "1.0.0",
        description = "订单查询与管理接口"
    )
)]
struct ApiDoc;

常见误区

  • 文档版本长期不更新:客户端无法判断 spec 对应哪次发布。
  • 元信息填写内部地址或敏感联系人:对外文档需按发布范围脱敏。

追问

  • 待确认:当前版本 info 支持的字段(contact/license/servers 等)写法,验证方式为 utoipa OpenApi 文档。
  • 多环境服务地址如何写?答:spec 中可声明 servers 列表,区分开发/生产环境,具体结构以 OpenAPI 规范与库实现为准。

04.4.9.2-058 公开接口与内部接口的文档如何裁剪?

一句话结论

按部署环境或受众分离 OpenApi 实例:对外文档只包含公开路径与组件,内部管理、运维接口单独生成文档并加访问控制。

概念解释

内部接口、后台管理、调试端点不应出现在公开 spec 中,避免暴露攻击面。实现方式是构造不同的 OpenApi 实例,分别登记路径与组件;文档端点本身也要鉴权。裁剪在代码组装层完成,而不是靠页面隐藏。

原理流程

  1. 划分公开与内部接口清单。
  2. 分别构造 OpenApi:公开实例只汇总公开路径与 DTO。
  3. 内部文档端点挂鉴权中间件。
  4. 生成环境确认对外 spec 不含内部路径。

代码或图示

// 思路:两个 OpenApi 实例分别登记不同 paths/components
// 公开实例:public_routes + public_schemas
// 内部实例:admin_routes + admin_schemas,独立鉴权端点

常见误区

  • Swagger UI 页面隐藏内部路由但 JSON 端点仍可访问:裁剪必须在 spec 生成层完成。
  • 内部 DTO 注册进公开组件:即使路径不暴露,结构定义也可能出现在公开 spec 中。

追问

  • 待确认:utoipa 是否支持按条件过滤路径/组件,验证方式为文档示例与 openapi.json 实际输出。
  • 生产环境文档默认策略是什么?答:建议默认关闭或鉴权访问,按需在测试/预发环境开放。

04.4.9.2-059 OpenAPI JSON 如何在运行时输出与落盘?

一句话结论

运行时由文档端点序列化 OpenApi 结构返回 JSON;构建或 CI 阶段也可调用生成逻辑把 spec 写入文件,纳入版本管理或供离线工具消费。

概念解释

运行时端点便于联调时查看最新文档;落盘 spec 用于契约测试、SDK 生成与评审归档。两种来源应保持同一生成逻辑,避免线上文档与归档文件不一致。落盘文件是派生产物,变更应随代码评审。

原理流程

  1. 构造 OpenApi 实例。
  2. 运行时:端点序列化返回 JSON 响应。
  3. CI/构建:调用同一生成代码写出 openapi.json。
  4. 归档 spec 与代码评审一起检查变更。

代码或图示

// 运行时端点示例
async fn spec() -> impl axum::IntoResponse {
    axum::Json(ApiDoc::openapi())
}

// 落盘方式:按项目脚本调用生成逻辑写入文件,具体命令以工程约定为准

常见误区

  • 归档 spec 手工编辑漂移:应从代码生成,不维护手写副本。
  • 只在本地生成不落盘:CI 无法检测文档与代码不一致。

追问

  • 待确认:utoipa 是否提供 CLI 或示例方式导出 spec 文件,验证方式为 utoipa 仓库示例与文档。
  • spec 文件纳入版本管理的利弊?答:可评审契约变更与做 diff 检测,代价是生成文件随代码更新;按项目契约流程决定。

04.4.9.2-060 遇到版本敏感的 utoipa/aide API,如何核对而不编造?

一句话结论

以 docs.rs 当前版本文档、示例工程与实际生成的 openapi.json 为准;不确定的属性名、feature、集成方式在题库与代码中标注「待确认」并写明验证点,不写死次版本号行为。

概念解释

文档库 API 随版本演进:宏参数名、组件拆分、框架集成方式都可能变化。核对路径:先查 crate 文档的当前版本章节,再看示例工程用法,最后用最小项目生成 spec 验证行为。项目依赖锁定后记录版本基线。

原理流程

  1. 打开对应 crate 的 docs.rs 页面确认当前版本。
  2. 查阅属性、trait 与集成组件清单。
  3. 最小示例编译并生成 spec 核对输出结构。
  4. 无法确认的条目标注待确认与验证方式,不凭记忆补全。

代码或图示

核对清单:
- 宏参数名与可选值
- feature/集成 crate 名称
- 类型推导结果(nullable/枚举/联合)
- 错误响应与组件注册 API
验证来源:docs.rs 当前版本文档 + 示例工程 + 生成的 openapi.json

常见误区

  • 沿用教程旧版本写法直接进生产:未核对兼容矩阵导致编译或文档缺失。
  • 把推测 API 写成确定结论:应标注待确认,避免误导后续维护者。

追问

  • 项目升级文档库先回归什么?答:生成的 spec 与关键接口样例比对,检查字段名、类型、枚举值与错误结构未变。
  • 文档库与框架版本如何对齐?答:查看库文档兼容说明,cargo 解析依赖后在最小集成示例验证。

04.4.9.2-061 aide crate 在 Rust 生态中如何定位?

一句话结论

aide 是面向 axum 生态的类型安全 OpenAPI 生成库:从 handler 签名与提取器类型派生操作描述与 schema,强调路由、提取器与文档模型一体生成。

概念解释

与 utoipa 的通用定位不同,aide 深度结合 axum:路由类型携带文档元信息,提取器实现对应文档 trait 后自动参与 schema 生成。它适合 axum 项目减少手写路径宏的工作量;非 axum 场景适用性有限。版本与 API 细节以当前文档为准。

原理流程

  1. 应用使用 aide 提供的路由类型注册 handler。
  2. handler 签名中的提取器与响应类型实现文档 trait。
  3. 库从类型信息派生 Operation 与 schema。
  4. 汇总生成 OpenAPI 文档并挂载文档页面。

代码或图示

# 名称与 feature 以 docs.rs/aide 当前版本为准(待确认)
[dependencies]
aide = "*"

常见误区

  • 把 aide 当通用框架文档库:其设计围绕 axum 提取器与路由模型,其他框架需另选方案。
  • 不核对版本就照搬示例:aide API 随版本演进,路由类型与响应 trait 名称可能调整。

追问

  • 待确认:aide 当前版本号、axum 兼容版本与 feature 清单,验证方式为 docs.rs/aide 与 crates.io。
  • aide 与 utoipa 能在同一项目混用吗?答:技术上可以但不建议,两套文档模型会增加维护成本,应按主框架选一套。

04.4.9.2-062 aide 的 ApiRouter、ApiExtractor 与 Operation 分别承担什么角色?

一句话结论

ApiRouter 是携带文档元信息的路由类型,ApiExtractor 标记参与文档生成的请求提取器,Operation 描述单个接口的操作元数据;三者协作把 axum 路由转为 OpenAPI 操作。

概念解释

aide 用带文档能力的类型替换 axum 原生路由:注册路由时累积操作描述,提取器告知库参数 schema,响应类型告知响应结构。Operation 汇总方法、路径、参数、请求体与响应。具体类型名与方法以当前版本文档为准。

原理流程

  1. 用 ApiRouter 注册 handler 路由。
  2. 提取器实现 ApiExtractor 类 trait,贡献参数 schema。
  3. handler 响应类型贡献响应 schema。
  4. 路由汇总为 Operation 列表,生成 OpenAPI 文档。

代码或图示

// 类型名与签名待确认,以 docs.rs/aide 当前版本示例为准
// use aide::{ApiRouter, openapi::Operation};
// let router: ApiRouter = ApiRouter::new().api_route("/items", get(handler));

常见误区

  • 用原生 axum Router 注册后期待 aide 自动生成文档:文档路由需要 aide 提供的类型承载元信息。
  • 自定义提取器不实现文档 trait:对应参数从文档中缺失。

追问

  • 待确认:当前版本 aide 路由方法名(api_route 等)、响应 trait 名与 Operation 构造方式,验证方式为 aide 文档与示例工程。

04.4.9.2-063 aide 如何从 handler 签名派生 schema 与 Operation?

一句话结论

handler 参数中的提取器类型与返回值类型实现文档 trait 后,aide 在路由注册时读取这些类型信息,自动汇总为参数、请求体与响应 schema,生成对应 Operation 描述。

概念解释

派生链路:路由类型累积 handler 引用,提取器实现贡献参数元信息,响应类型实现贡献响应 schema。相比手写路径宏,类型签名变化时文档随之更新;自定义提取器与响应包装需要补充对应文档实现,否则该部分 schema 缺失。

原理流程

  1. handler 声明提取器参数与响应返回类型。
  2. 各类型实现 aide 的文档 trait。
  3. 路由注册时读取签名信息组装 Operation。
  4. 全部 Operation 汇总生成 OpenAPI 文档。

代码或图示

// 签名与 trait 名待确认,以 docs.rs/aide 当前版本为准
// async fn handler(Path(id): Path<u64>) -> impl IntoApiResponse { ... }
// 库从 Path 提取器与返回类型推导参数与响应 schema

常见误区

  • 自定义提取器只实现 axum 提取 trait 不实现文档 trait:参数 schema 不出现在文档中。
  • 响应包装类型绕过文档实现:外层包装结构丢失,内部 DTO 无法被正确引用。

追问

  • 待确认:aide 内置提取器(Path/Query/Json 等)是否自动派生文档参数,验证方式为 aide 提取器文档。
  • handler 签名修改后文档如何同步?答:类型驱动派生自动更新,仍需在生成 spec 中核对变更是否符合预期。

04.4.9.2-064 aide 与 utoipa 如何取舍?

一句话结论

axum 项目可优先评估 aide 的类型一体派生;需要框架中立、更成熟的 schema 生态或其他框架配合时选 utoipa;选型以真实 DTO 与接口文档生成结果对比为准。

概念解释

两者核心差异:aide 与 axum 路由/提取器模型绑定,签名驱动;utoipa 通用框架,靠 handler 宏与 ToSchema 派生。对比维度包括:规则与错误体系无关、schema 推导覆盖度、文档组件生态、维护活跃度、团队上手成本。项目主框架确定后,文档库应与之匹配。

原理流程

  1. 列出项目常用 DTO 形态与接口类型。
  2. 在两个库的最小示例中生成同一组文档。
  3. 比对字段推导、错误响应、UI 挂载与维护状态。
  4. 确定主用库并在工程约定中固定,避免混用两套模型。

代码或图示

aide:axum 路由/提取器签名驱动,集成紧
utoipa:框架中立,路径宏 + ToSchema,生态组件多
对比:schema 覆盖、错误响应文档、集成难度、当前版本活跃度

常见误区

  • 只看库流行度选型:与主框架的契合度才是首要标准。
  • 项目内两个库并行:文档模型重复维护,错误响应与 schema 结构难以统一。

追问

  • 待确认:两库当前版本号、最近发布时间与 issue 处理状态,验证方式为 crates.io 与 docs.rs。
  • 已有 utoipa 项目迁到 aide 成本多大?答:路径宏与 schema 标注需重写为类型驱动,业务 DTO 与校验层基本不受影响。

04.4.9.2-065 什么是「文档即契约」,如何防止 schema 与实现漂移?

一句话结论

文档即契约指接口结构以代码派生的 schema 为准并被前端、Mock、测试共同消费;防漂移靠类型同源生成、CI 比对生成 spec 与回归测试,而不是手工维护文档副本。

概念解释

漂移来源:文档手写过期、字段改名未同步、错误响应未登记。同源派生让类型定义同时决定运行时序列化与文档 schema;CI 检测 spec 变更并评审,测试断言实际响应结构与文档一致。文档是代码的派生产物,不是独立维护的说明文。

原理流程

  1. DTO 类型同时支撑序列化与 schema 派生。
  2. 接口 handler 登记文档操作与响应。
  3. CI 生成 spec 并与归档版本 diff,评审变更。
  4. 集成测试断言响应字段与 schema 约定一致。

代码或图示

单一来源:Rust DTO 类型
  → 运行时 JSON 序列化(Serde)
  → OpenAPI schema(utoipa/aide)
  → Mock / SDK / 契约测试消费

常见误区

  • 文档页面人工补充字段说明后不回写类型:说明与类型分叉。
  • spec 变更不评审直接合入:breaking change 可能未通知消费方。

追问

  • 派生文档仍可能与实际响应不一致吗?答:会,例如 Serde 自定义属性未被 schema 识别,需用测试与 spec 对照检查。
  • 契约漂移如何监控?答:CI 生成 spec 做 diff,关键接口用契约测试比对实际响应结构。

04.4.9.2-066 API 版本与灰度发布在契约层面如何组织?

一句话结论

版本通过路由前缀或请求头隔离,每个版本对应独立 OpenApi 文档;灰度期间新旧契约并存,变更按兼容策略发布,废弃版本保留到客户端迁移完成。

概念解释

接口版本管理避免改动打断旧客户端:常见做法是 URL 前缀(/v1、/v2)或版本请求头。每个版本路径与 DTO 独立登记文档,灰度流量按版本分流。废弃字段与版本需要迁移期说明,不能直接删除。

原理流程

  1. 确定版本策略:前缀、请求头或内容版本号。
  2. 新旧版本路由与 DTO 并行注册。
  3. 各版本生成对应 OpenApi 文档。
  4. 旧版本进入废弃期,客户端迁移完成后下线路由与文档。

代码或图示

/v1/users   → v1 DTO 与 v1 文档
/v2/users   → v2 DTO 与 v2 文档
灰度:按流量或租户版本分流,契约各自独立

常见误区

  • 字段不兼容改动直接覆盖旧版本:未迁移客户端调用失败。
  • 文档不按版本分离:消费方看到混合新旧结构,无法判断适用契约。

追问

  • 待确认:项目现有版本前缀约定与灰度分流方式,验证方式为项目路由与部署配置。
  • 新增字段算 breaking change 吗?答:向后兼容的可选新增通常不破坏旧客户端;删字段、改类型、收紧必填属于 breaking change。

04.4.9.2-067 请求 DTO 与响应 DTO 为什么要分离?

一句话结论

请求与响应的字段集合、可空性与语义不同:分离后避免内部字段外泄、避免客户端写入服务端生成字段,两个方向独立演进。

概念解释

请求模型接收客户端输入(可填写字段、可选校验),响应模型返回服务端结果(生成字段、聚合数据)。复用同一结构会导致权限字段、内部状态出现在输入或输出中。分离后 DTO 之间通过应用层转换,领域模型不直接暴露在接口边界。

原理流程

  1. 定义 CreateXxx/UpdateXxx 请求 DTO,derive 反序列化。
  2. 定义 XxxResponse 响应 DTO,derive 序列化与 schema。
  3. 服务层完成领域模型与两个 DTO 的转换。
  4. 接口签名只出现专用 DTO,不出现内部实体。

代码或图示

use serde::{Serialize, Deserialize};

#[derive(Deserialize)]
struct CreateOrder { sku: String, qty: u32 }

#[derive(Serialize, utoipa::ToSchema)]
struct OrderResponse { id: u64, sku: String, qty: u32, status: String }

常见误区

  • 一个 DTO 同时承载创建、更新与响应:字段语义互相牵制,演进牵一发动全身。
  • 响应 DTO 保留请求才有的字段:多余结构出现在对外文档与响应中。

追问

  • 查询参数 DTO 属于哪一类?答:属于请求侧,按查询/路径/头参数建模,与响应模型分开。
  • 两个 DTO 字段重复如何避免冗余?答:共享只读字段结构可抽取公共片段,可变与生成字段保持各自独立。

04.4.9.2-068 跨端字段命名如何保持兼容与一致?

一句话结论

对外命名风格在契约层固定(如 camelCase 或 snake_case),通过 Serde rename 与 schema 属性同步到序列化与文档;字段改名属于契约变更,需按版本策略过渡。

概念解释

Rust 习惯 snake_case,前端常用 camelCase。命名映射集中在 DTO 边界:Serde 属性控制 JSON 键,schema 属性控制文档键,两边必须一致。历史接口兼容期用 alias 接收旧名,响应输出规范名。命名规范应在团队契约文档中统一。

原理流程

  1. 确定对外命名风格规范。
  2. DTO 字段按内部习惯命名,属性映射外部键。
  3. Serde 与 ToSchema 两侧键名保持一致。
  4. 改名走兼容期:先双名接收,再切换规范输出,最后移除旧名。

代码或图示

use serde::Serialize;
use utoipa::ToSchema;

#[derive(Serialize, ToSchema)]
struct ItemDto {
    #[serde(rename = "itemId")]
    #[schema(rename = "itemId")]
    id: u64,
}

常见误区

  • 只改 Serde 键名不同步 schema:文档与实际响应键名不一致。
  • 字段重命名直接删除旧名:仍在使用旧名的客户端解析失败。

追问

  • 命名风格冲突时以谁为准?答:以对外消费方生态习惯为准,内部 Rust 命名不渗透到契约。
  • 缩写字段(URL/ID)大小写如何约定?答:在命名规范中固定缩写形态,文档与代码保持同一写法。

04.4.9.2-069 枚举变体演进时,新增、废弃、重命名各有什么契约影响?

一句话结论

新增可选变体向后兼容;废弃变体需保留接收期再下线;重命名或删除变体属于 breaking change;客户端对未知变体的处理策略要在契约中说明。

概念解释

枚举是跨端契约的敏感部分:客户端通常按变体分支处理逻辑。新增值若旧客户端未识别,可能落入默认分支或报错;删除/改名让旧引用失效。演进遵循:先加新变体并兼容未知值,标记废弃,迁移完成后再移除旧变体。

原理流程

  1. 评估变更类型:新增/废弃/改名/删除。
  2. 新增:服务端与文档先上线,客户端逐步识别新值。
  3. 废弃:旧变体保留接收能力,文档标注弃用。
  4. 删除/改名:新版本路由承载,旧版本保留到迁移完成。

代码或图示

兼容:新增枚举值,旧客户端走未知值兜底
风险:删除/改名变体,旧客户端分支失效
兜底:接口约定未知变体的默认处理与错误返回

常见误区

  • 直接在同一版本替换枚举取值:旧客户端反序列化未知变体失败。
  • 文档不标注废弃状态:消费方不知道旧变体何时下线。

追问

  • 反序列化遇到未知变体如何兜底?答:类型设计可加未知变体承接,或在服务层宽松处理;策略写入契约。
  • 枚举值改为数字编码影响多大?答:属于表示形式变更,跨端识别逻辑全部受影响,应按新版本发布。

04.4.9.2-070 分页结构的 DTO 如何设计?

一句话结论

分页请求区分页码/每页条数或偏移/限制两种模式;响应携带当前页数据、总数与分页参数;结构在 DTO 与 OpenAPI 中统一表达,避免各接口自创分页格式。

概念解释

常见分页模型:page + page_size(页码制)或 offset + limit(偏移制)。响应包含列表、总条数与回显分页参数。分页结构可抽成通用包装 DTO 复用。上限约束(每页最大条数)在校验与框架层兜底,防止超大列表。

原理流程

  1. 定义分页请求字段:页码/条数或偏移/限制。
  2. 校验边界:页码从 1 起,条数在 1 到上限之间。
  3. 响应 DTO 包含 items、total 与分页回显。
  4. 通用包装结构在 schema 中注册为复用组件。

代码或图示

use serde::Serialize;
use utoipa::ToSchema;

#[derive(Serialize, ToSchema)]
struct Page<T: Serialize + ToSchema> {
    items: Vec<T>,
    total: u64,
    page: u32,
    page_size: u32,
}

常见误区

  • 各接口分页字段名不一致:前端无法复用列表处理逻辑。
  • 响应不返回总数:客户端无法计算总页数与是否还有下一页。

追问

  • 待确认:泛型包装 DTO 在当前 utoipa 版本的 schema 推导支持情况,验证方式为生成的 spec。
  • 深分页(大 offset)如何治理?答:偏移分页有性能边界,深翻场景考虑游标/键集分页,结构在契约中单独约定。

04.4.9.2-071 统一响应包装结构如何设计并在 OpenAPI 中表达?

一句话结论

包装结构统一承载业务码、消息与数据负载;成功与错误各有对应 DTO,泛型数据部分在 schema 中表达为可替换组件;包装层级全接口保持一致。

概念解释

统一包装让前端用同一套逻辑解包:code、message、data 或 items。包装结构与分页、错误体配合使用:成功响应包数据,失败响应包错误详情。泛型包装在文档库中的推导能力需核对,必要时为主要响应类型各写具体 DTO。

原理流程

  1. 定义通用成功包装与错误包装 DTO。
  2. 业务 handler 按包装结构返回响应。
  3. DTO 注册为 schema 组件,响应引用包装类型。
  4. 文档示例与实际响应保持同一包装层级。

代码或图示

use serde::Serialize;
use utoipa::ToSchema;

#[derive(Serialize, ToSchema)]
struct ApiResp<T: Serialize + ToSchema> {
    code: String,
    message: String,
    data: T,
}

常见误区

  • 部分接口裸返回数据、部分套包装:前端解包逻辑分叉,文档结构不统一。
  • 包装内字段命名与错误响应不一致:契约两套约定增加对接成本。

追问

  • HTTP 状态码与业务 code 重复吗?答:状态码表达传输层结果,业务 code 表达应用场景,两者并存并在文档中说明映射关系。
  • 待确认:文档库对泛型 ApiResp<T> 的 schema 生成结果,验证方式为 openapi.json 中 data 字段类型。

04.4.9.2-072 错误响应契约应包含哪些内容?

一句话结论

错误契约包含 HTTP 状态码、业务错误码、人类可读消息、字段级问题列表(路径/规则码/参数)与请求标识;结构全接口统一,敏感内部细节不暴露。

概念解释

客户端需要三类信息:发生了什么(错误码与消息)、哪里出错(字段路径)、如何追踪(请求 ID)。字段级问题用于表单高亮,业务码用于分支处理,请求 ID 关联服务端日志。错误体结构在 DTO 中固定并纳入 OpenAPI 文档。

原理流程

  1. 定义错误响应 DTO:code/message/issues/request_id。
  2. 校验错误与业务错误分别映射到该结构。
  3. 敏感细节只写日志,响应暴露摘要。
  4. 文档登记错误状态码与错误体 schema。

代码或图示

{
  "code": "validation_failed",
  "message": "参数校验未通过",
  "request_id": "req-7f3a",
  "issues": [
    { "field": "email", "code": "email", "message": "邮箱格式不正确" }
  ]
}

常见误区

  • 错误体直接返回内部异常消息或堆栈:泄露实现细节,存在安全风险。
  • 字段路径使用 Rust 内部名:对外应使用契约字段名。

追问

  • 错误消息多语言在哪一层处理?答:错误转换层按请求语言取模板,错误码与参数是模板输入。
  • 待确认:项目现有统一错误体字段名与状态码映射,验证方式为已有 handler 错误实现。

04.4.9.2-073 DTO 与领域模型之间的映射层放在哪里?

一句话结论

转换发生在应用服务层或独立转换模块:DTO 不直接持有领域实体,领域模型也不依赖接口格式;From/TryFrom 或专用映射函数集中管理。

概念解释

分层依赖方向:接口层 → 应用层 → 领域层,DTO 与领域模型互不反向依赖。映射负责字段搬运、值规范化与错误转换。映射代码集中在转换模块,避免散落在各 handler 中重复编写。

原理流程

  1. 请求 DTO 进入应用服务层。
  2. 服务层调用映射构造领域命令或实体。
  3. 业务处理后领域结果映射为响应 DTO。
  4. 接口只序列化响应 DTO,不暴露内部模型。

代码或图示

struct CreateUserCmd { name: String }
struct User { id: u64, name: String }

fn to_cmd(dto: CreateUserDto) -> CreateUserCmd {
    CreateUserCmd { name: dto.name }
}

fn to_response(u: User) -> UserResponse {
    UserResponse { id: u.id, name: u.name }
}

常见误区

  • 领域实体直接作为 handler 返回类型:内部结构与字段外泄,序列化边界渗透到领域层。
  • 映射逻辑写在 DTO 方法里依赖领域类型:反向依赖破坏分层。

追问

  • 映射需要校验补充逻辑吗?答:形态规则在 DTO 校验层,业务不变量在领域层,映射只做搬运与归一化。
  • 复杂聚合如何映射为多个响应 DTO?答:按用例组装不同响应视图,一个聚合可对应多个响应模型。

04.4.9.2-074 敏感字段在响应 DTO 中如何排除?

一句话结论

响应模型不定义敏感字段;需要脱敏的字段在映射层转换为脱敏形态;序列化侧用 skip 或专用响应类型排除内部字段,避免通过实体复用外泄。

概念解释

敏感信息包括密码哈希、令牌、内部标识、隐私联系方式等。防御层次:响应 DTO 字段集合白名单化;映射层做脱敏(掩码、部分隐藏);序列化属性跳过内部字段。不信任单一保护层,输入输出两侧都检查字段集合。

原理流程

  1. 定义响应 DTO 时只列入可对外字段。
  2. 映射层对需要展示的值做脱敏处理。
  3. 内部实体字段不进入响应结构;必要时用 skip 排除。
  4. 评审与测试检查响应体不含敏感原值。

代码或图示

use serde::Serialize;

#[derive(Serialize)]
struct PublicProfile {
    nickname: String,
    #[serde(skip_serializing)]
    internal_note: String,
}

fn mask_email(email: &str) -> String {
    let (a, b) = email.split_once('@').unwrap_or((email, ""));
    format!("{}***@{}", &a[..1.min(a.len())], b)
}

常见误区

  • 复用带敏感字段的内部实体做响应:字段随序列化全部外泄。
  • 只在前端隐藏敏感值:响应体已包含原值,前端隐藏不构成防护。

追问

  • 密码哈希为什么绝不能出现在响应?答:哈希是认证凭据材料,泄露后可被离线爆破,任何场景都不应返回。
  • 日志与响应如何分工?答:敏感值按策略脱敏后入日志,响应体只暴露必要的公开信息。

04.4.9.2-075 大 DTO 如何在嵌套与扁平之间取舍?

一句话结论

按业务聚合关系组织嵌套,按消费便利组织扁平;字段分组清晰、层级不过深,重复出现的片段抽成复用结构;嵌套层级在文档与前端类型中保持可读。

概念解释

嵌套结构表达从属关系(地址、明细行),扁平结构便于直接取值。大对象平铺所有字段会导致分组不清,过度嵌套增加前端取值层级。取舍标准:同一业务聚合同组、跨用例重复片段抽取、层级控制在两三层以内。

原理流程

  1. 梳理字段所属业务分组。
  2. 从属关系强的字段组成嵌套 DTO。
  3. 跨接口复用的片段抽为公共结构。
  4. 检查文档 schema 层级与前端取值路径是否合理。

代码或图示

use serde::Serialize;
use utoipa::ToSchema;

#[derive(Serialize, ToSchema)]
struct OrderView {
    id: u64,
    receiver: Receiver,
    items: Vec<Line>,
}

#[derive(Serialize, ToSchema)]
struct Receiver { name: String, phone: String }

常见误区

  • 所有字段平铺成一层:对象职责不清,字段语义靠命名猜测。
  • 为复用强行嵌套:片段与主对象生命周期不同,嵌套反而耦合。

追问

  • flatten 适合什么场景?答:公共片段需要与主对象同层输出时使用,注意键名唯一与文档识别。
  • 嵌套过深如何判断?答:前端取值路径层级与 schema 嵌套层数作为参考指标,过深则拆分视图 DTO。

04.4.9.2-076 如何判断一次 DTO 变更是向后兼容还是 breaking change?

一句话结论

向后兼容:新增可选字段、放宽校验、增加枚举值;breaking change:删除字段、改字段类型、必填收紧、重命名字段、改枚举取值;变更前对照旧客户端解析规则逐项判定。

概念解释

兼容性以旧客户端能否继续解析与处理新契约为准。新增可选字段旧客户端可忽略;删除或改名导致旧引用失效;类型变化(数字转字符串、对象转数组)破坏解析;必填收紧让原本合法的请求被拒。契约变更需要版本策略配合。

原理流程

  1. 列出变更字段与类型差异。
  2. 按兼容清单分类:兼容新增、风险调整、breaking 删除/改名/改类型。
  3. breaking 变更走新版本路由或迁移期过渡。
  4. CI 比对 spec diff,评审每项变更的兼容性。

代码或图示

兼容:新增可选字段、新增枚举值、放宽长度/范围
风险:字段语义调整、错误码变更、分页模型变化
Breaking:删除/重命名字段、改类型、必填化、枚举值移除

常见误区

  • 认为服务端加字段一定安全:若新字段为必填或改变默认行为,旧客户端可能受影响。
  • 忽略响应方向兼容:前端按旧结构解析新响应同样可能失败。

追问

  • 待确认:项目契约变更评审流程与版本发布约定,验证方式为项目文档与发布记录。
  • 如何自动化检测 breaking change?答:比对相邻版本 openapi.json 的字段、类型、必填与枚举差异,列入 CI 检查。

04.4.9.2-077 什么是契约测试,在 Rust 项目中如何落地?

一句话结论

契约测试验证服务提供的接口符合约定 schema 与行为:请求样例通过校验,响应结构、字段类型与错误码匹配文档;在 Rust 中用集成测试 + spec 断言或契约工具链落地。

概念解释

单元测试覆盖内部逻辑,契约测试站在消费方角度验证对外接口:路径、参数、请求/响应结构、错误场景。落地方式:起测试服务发真实请求,断言状态码与响应字段;或导入 openapi.json 校验响应实例。契约测试防止实现与文档漂移。

原理流程

  1. 准备合法请求与各类非法请求样例。
  2. 测试中启动或连接服务发送请求。
  3. 断言状态码、响应结构与字段类型符合 DTO/schema。
  4. 错误场景断言字段路径与错误码。

代码或图示

// 思路:oneshot 或测试服务发送请求,反序列化响应 DTO 后断言字段
// 与 openapi.json 对照:可选 schema 校验工具按当前生态选型(待确认)
#[tokio::test]
async fn create_rejects_short_name() {
    // 发送请求 → 断言 422 → 断言 issues 包含 name 字段
}

常见误区

  • 只测成功路径:错误响应契约未覆盖,漂移发现不了。
  • 契约测试依赖生产环境:应使用测试服务与替身依赖,保证可重复执行。

追问

  • 待确认:Rust 生态中导入 OpenAPI 校验响应的现成工具与活跃度,验证方式为 crates.io 检索与文档。
  • 契约测试与端到端测试区别?答:契约聚焦结构与约定一致性,E2E 覆盖完整业务链路,两者互补。

04.4.9.2-078 如何把 schema 变更纳入版本管理并做 diff 检测?

一句话结论

CI 从代码生成 openapi.json 并与归档版本比对,字段、类型、必填、枚举差异进入评审;生成文件作为派生产物纳入版本管理,变更随代码评审。

概念解释

归档 spec 是契约基线:每次构建生成新 spec,与仓库中上次归档版本 diff。新增字段、类型调整、删除项都在 diff 中可见,评审判断兼容性。纯文档注释变化不应造成结构 diff,结构变更必须对应代码变更。

原理流程

  1. 构建/CI 步骤生成当前 openapi.json。
  2. 读取仓库归档基线版本。
  3. 程序化比对 paths、components、字段类型与必填。
  4. 输出变更报告,breaking 项阻断或人工评审。

代码或图示

代码 DTO/handler
  → CI 生成 openapi.json
  → diff 基线 spec
  → 变更清单评审:兼容 / 风险 / breaking

常见误区

  • 归档 spec 手工编辑:diff 基线失真,无法反映代码真实契约。
  • 只在本地生成不入库:团队无法跨次比对契约演进。

追问

  • spec 文件放项目什么位置?答:按工程约定存放派生产物目录,生成脚本纳入构建流程;具体路径以项目目录规范为准。
  • 待确认:项目现有 CI 是否包含文档生成步骤,验证方式为工程配置与构建脚本。

04.4.9.2-079 如何检测删除字段、收紧类型、改必填等 breaking change?

一句话结论

对比相邻版本 schema:字段移除/重命名、类型收窄或放宽、可选改必填、枚举值删除属于 breaking;检测规则按字段级 diff 分类,结果输出为评审清单或阻断门禁。

概念解释

breaking 检测需要结构化比对而不是文本 diff:逐路径逐字段检查存在性、类型、必填标记、枚举集合。服务端视角的收紧(必填化、范围变小)与客户端视角的删除都要识别。兼容新增(可选字段、新枚举值)标记为低风险。

原理流程

  1. 解析新旧两份 openapi.json。
  2. 按路径与字段对齐结构。
  3. 分类差异:新增可选、类型变化、必填变化、字段删除、枚举收缩。
  4. breaking 项输出清单,按策略阻断或要求评审确认。

代码或图示

检测项:
- 字段:缺失 / 新增 / 重命名
- 类型:string ↔ number、object ↔ array
- 必填:optional → required
- 枚举:取值集合收缩
- 响应状态码:成功/错误码移除

常见误区

  • 文本 diff 代替结构化比对:键顺序变化会产生噪声,类型变更可能漏检。
  • 只检查请求方向:响应结构破坏同样影响前端。

追问

  • 待确认:Rust 生态现成的 OpenAPI diff 工具链与项目可接入方案,验证方式为 crates.io 与 CI 配置。
  • 检测出 breaking 后流程是什么?答:按版本策略走新版本或迁移期,评审记录兼容说明,通知消费方。

04.4.9.2-080 CI 中如何校验文档与代码一致?

一句话结论

CI 步骤生成 OpenAPI spec 并校验:文档可解析、响应/参数类型已注册、生成 spec 与归档基线 diff 通过;编译与测试通过作为前置条件。

概念解释

一致性校验覆盖:OpenApi 结构能正常序列化,引用的 schema 组件存在,路径与 Web 路由对应,关键接口响应有文档。把文档生成纳入 CI 而不是本地手工产出,避免过期文档进入主干。

原理流程

  1. CI 执行编译与测试。
  2. 运行文档生成逻辑产出 spec。
  3. 校验 spec 可解析、组件引用完整。
  4. 与基线 diff 比对,变更进入评审门禁。

代码或图示

CI 流程:
cargo test → 生成 openapi.json → 校验引用完整 → diff 基线 → 评审/阻断

常见误区

  • 文档只在开发机器生成:CI 无法发现 handler 未登记响应、组件未注册。
  • 生成失败仍放行:缺失 schema 的接口带病进入主干。

追问

  • 待确认:项目 CI 现有步骤与文档生成接入点,验证方式为工程配置与构建脚本。
  • 本地如何预校验?答:提交前运行同一文档生成命令,确认 spec 无解析错误再推送。

04.4.9.2-081 openapi.json 如何被前端、Mock 与 SDK 工具消费?

一句话结论

spec 作为机器可读契约输入代码生成器:生成前端类型与请求函数、Mock 服务样例、客户端 SDK;消费方按 spec 而非阅读页面文档对接。

概念解释

OpenAPI JSON 是工具链输入:类型生成器产出 TypeScript 类型与 API 客户端,Mock 工具按 schema 造样例数据,测试工具按参数发请求。服务端保持 spec 同源生成,消费方工具链自动跟进契约变更。

原理流程

  1. 服务端生成并发布当前 openapi.json。
  2. 前端工程运行代码生成器产出类型与请求封装。
  3. Mock 按响应 schema 生成样例数据。
  4. 契约变更后重新生成消费侧代码并回归。

代码或图示

openapi.json
  → 前端类型 / 请求函数生成
  → Mock 服务样例数据
  → 客户端 SDK 生成
  → 契约测试与文档页面

常见误区

  • 前端手写类型与 spec 脱节:字段演进时类型不同步,应以生成代码为准。
  • Mock 样例不符合校验规则:示例值应满足长度、范围等约束。

追问

  • 待确认:项目前端侧使用的 OpenAPI 代码生成工具,验证方式为前端工程配置。
  • spec 发布到哪里供消费方?答:可由文档端点提供或随构建产物归档,按团队协作流程确定。

04.4.9.2-082 接口示例值与 Mock 数据如何保证与测试响应一致?

一句话结论

schema 中的 example 应满足校验规则并与集成测试样例一致;Mock 数据从同一组样例派生,避免文档示例、Mock、真实响应三者结构分叉。

概念解释

示例值用于文档展示与工具调试:格式、长度、范围必须合法。测试样例是真实链路验证过的结构,最可靠。维护方式:共享样例数据或在测试中断言示例字段类型,文档 example 与测试响应对齐。

原理流程

  1. 准备满足校验规则的合法样例。
  2. 测试用该样例发送请求并断言响应。
  3. 文档 example 取自同一样例字段值。
  4. 接口变更时同步更新样例、测试与文档。

代码或图示

use utoipa::ToSchema;

#[derive(ToSchema)]
struct Product {
    #[schema(example = "SKU-0001")]
    sku: String,
    #[schema(example = 19.9)]
    price: f64,
}

常见误区

  • example 违反长度/格式规则:Mock 生成无效数据,误导对接。
  • 文档示例与测试响应字段不一致:消费方按示例对接后真实接口报错。

追问

  • 复杂响应示例如何维护?答:用测试固定合法响应快照,文档示例引用同结构字段,变更时回归比对。
  • 待确认:文档库 example 是否参与 schema 校验,验证方式为当前版本文档与生成 spec。

04.4.9.2-083 综合:一个 axum 接口从 DTO、校验到 OpenAPI 文档的完整链路是什么?

一句话结论

链路为:定义请求/响应 DTO → Serde 反序列化 → DTO 规则校验 → 服务层业务处理 → 响应 DTO 序列化 → 类型派生 OpenAPI 文档并挂载 spec 与 UI。

概念解释

完整链路串联本主题各环节:类型定义同时支撑序列化、校验与文档;提取器完成结构解析,校验层拦截非法输入,服务层执行业务规则,响应经映射层返回;文档从同一类型派生,避免三处各自维护。

原理流程

  1. 定义 CreateXxx 请求 DTO 与 XxxResponse 响应 DTO,标注 Serde 与 schema 派生。
  2. axum handler 用提取器反序列化请求体,结构失败返回提取器拒绝响应。
  3. 调用 DTO 校验规则,失败聚合为 422 字段错误。
  4. 服务层执行业务规则,领域结果映射为响应 DTO。
  5. 响应序列化返回;OpenApi 汇总路径与组件,挂载 openapi.json 与 Swagger UI。

代码或图示

use serde::{Serialize, Deserialize};
use utoipa::ToSchema;
use validator::Validate;

#[derive(Deserialize, Validate)]
struct CreateItem {
    #[validate(length(min = 2, max = 64))]
    name: String,
}

#[derive(Serialize, ToSchema)]
struct ItemResponse { id: u64, name: String }

// handler:Json 提取 → validate → 服务层 → Json(ItemResponse)
// 文档:#[utoipa::path] 登记请求/响应,OpenApi 注册 ItemResponse 组件

常见误区

  • 各环节使用不同类型定义:序列化、校验、文档三处字段集合不一致。
  • 跳过 DTO 校验直接进业务:非法输入绕过边界规则,错误延迟到数据层暴露。

追问

  • 这条链路上哪些部分需要测试覆盖?答:提取拒绝、校验失败、业务错误、成功响应四类路径,文档 spec 组件引用完整性单独校验。
  • 待确认:项目当前 axum 版本与文档库集成方式,落地前以 docs.rs 当前版本与工程已有实现为准。
  • aide 如何处理错误响应?答:响应类型实现文档 trait 后登记到操作响应列表,具体写法以版本文档为准。