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

04.4.9.3 GraphQL与DTO版本演进

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

04.4.9.3-001 async-graphql 在 Rust 后端生态中承担什么角色?

一句话结论

async-graphql 是 Rust 生态中主流的 GraphQL 服务端库,通过 derive 宏把 Rust 结构体与方法映射成 GraphQL 类型与字段解析器,配合 Web 框架(如 axum)对外暴露单一 GraphQL 端点。

概念解释

GraphQL 服务端要完成三件事:把内部领域类型映射为 schema 类型、按查询树逐层调用 resolver、把执行结果组装成 JSON 响应。async-graphql 用 #[Object]、#[InputObject]、#[Subscription] 等派生宏生成 schema 元数据,用 Schema 类型持有 Query/Mutation/Subscription 三个根节点。与 REST 不同,端点通常只有一个,查询的形状由请求体里的 GraphQL 查询字符串决定。

原理流程

  1. 在 Cargo.toml 引入 async-graphql 与对应框架集成包(如 async-graphql-axum)。
  2. 定义根 Query、Mutation、Subscription 结构体并挂派生宏。
  3. Schema::build(...) 组装根节点,注册全局数据后 finish()。
  4. Web 框架把 GraphQL 请求交给库执行:解析查询、校验类型、并发调用各 resolver。
  5. 按请求选择的字段收集结果,序列化为 GraphQL 响应 JSON。

代码或图示

[dependencies]
async-graphql = "*"
async-graphql-axum = "*"
use async_graphql::{Schema, Object};

struct Query;

#[Object]
impl Query {
    async fn ping(&self) -> &'static str { "pong" }
}

let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();

常见误区

  • 以为 GraphQL 可以替代所有 HTTP 中间件:鉴权、CORS、body 限制仍由 Web 框架层处理。
  • 以为 schema 在运行时手工拼装:async-graphql 主要靠 derive 从 Rust 类型推导。

追问

  • 它和 juniper 是什么关系?答:两者都是 Rust GraphQL 库,async-graphql 生态更新更快、宏驱动;juniper 历史更久、设计偏执行器抽象。
  • 版本敏感 API 在哪核对?答:以 docs.rs/async-graphql 当前版本为准,feature 开关与宏名需对照文档确认。

04.4.9.3-002 如何用 Schema::build 注册 Query、Mutation 与 Subscription 三个根节点?

一句话结论

Schema::build(query_root, mutation_root, subscription_root) 按顺序接收三个根节点,三者分别对应查询、写入与订阅操作;无对应能力时用 EmptyMutation、EmptySubscription 占位。

概念解释

GraphQL schema 必须有一个 Query 根类型;Mutation 与 Subscription 是可选根类型。async-graphql 要求 Schema::build 传入三个参数,即使某类操作不存在,也得用空根类型补齐类型位。根节点上的方法会成为 schema 顶层字段,客户端只能从这些顶层字段进入数据图。

原理流程

  1. 定义 struct Query 并 #[Object] 实现只读方法。
  2. 定义 struct Mutation 承载写操作,定义 struct Subscription 承载订阅流。
  3. 调用 Schema::build(query, mutation, subscription),链式 .data(...) 注入共享资源。
  4. finish() 得到不可变 Schema,可放入 axum State 共享给所有请求。
  5. 请求执行时按操作类型分发到对应根节点的 resolver。

代码或图示

use async_graphql::{EmptyMutation, EmptySubscription, Schema, Object};

struct Query;
#[Object] impl Query { async fn hello(&self) -> &'static str { "world" } }

let schema = Schema::build(Query, EmptyMutation, EmptySubscription)
    .finish();

常见误区

  • 把写操作写在 Query 根上:虽然能跑,但破坏语义约定,也绕过了 Mutation 的审核与缓存假设。
  • 以为 Schema 可以每次请求重建:应构建一次后共享,内部持有类型元数据与注册的全局数据。

追问

  • 三个根节点的 trait 约束分别是什么?答:Query/Mutation 实现 #[Object],Subscription 实现订阅派生宏;具体 trait 名以 docs.rs 当前版本为准。
  • 根节点上能否直接持有连接池?答:可以通过字段或 Data 注入,但更推荐把外部资源放进 Data,根结构体只做 schema 编排。

04.4.9.3-003 #[Object] 派生对结构体和方法签名提出了什么要求?

一句话结论

#[Object] 作用在结构体或其 impl 块上,方法即字段 resolver;方法第一个参数通常是 &self,可加 ctx: &Context<'_>,返回类型需实现 OutputType,可包一层 Result<T, E>。

概念解释

在 async-graphql 中,普通结构体经 #[Object] 映射为一个 GraphQL 对象类型,结构体上的异步方法变成可被查询的字段。方法参数除 &self 外,可声明上下文与参数;返回 Result 时错误会走 GraphQL 错误通道。字段名默认取方法名,可用 #[graphql(name = "...")] 覆盖。

原理流程

  1. 给结构体 impl 块加 #[Object],库在编译期扫描其中的公开方法。
  2. 每个方法被包装成字段 resolver:参数映射为 GraphQL 参数,返回值映射为字段类型。
  3. 生成实现 OutputType 的代码,注册进 schema 的类型表。
  4. 查询命中字段时,运行时构造 Context 并调用对应异步方法。
  5. 返回 Err 时错误进入响应的 errors 数组,不影响其他无依赖字段。

代码或图示

use async_graphql::{Object, Context, Result};

struct User { id: u64, name: String }

#[Object]
impl User {
    async fn id(&self) -> u64 { self.id }
    async fn name(&self) -> &str { &self.name }
    async fn greeting(&self, ctx: &Context<'_>, prefix: Option<String>) -> Result<String> {
        Ok(format!("{} {}", prefix.unwrap_or_else(|| "hi".into()), self.name))
    }
}

常见误区

  • resolver 方法返回同步阻塞计算:会卡住异步任务,重计算应拆到阻塞线程池。
  • 在 resolver 里持有 &self 之外的可变引用:对象通常按不可变共享设计,跨请求共享状态要走 Data 或内部可变性。

追问

  • 方法返回类型必须是 Result 吗?答:不是,普通可序列化类型可直接返回;可能失败时用 Result<T, FieldError> 携带错误信息。
  • 字段参数的默认值如何声明?答:Option<T> 表示可选,必填参数用 T;默认值表达式的具体宏写法以 docs.rs 当前版本为准。

04.4.9.3-004 Query 根 resolver 的入参与返回值如何映射到 GraphQL 字段参数?

一句话结论

Query resolver 方法上的普通参数(除 &self、ctx)会变成字段的 GraphQL 参数,标量或对象类型映射为对应输入类型;返回值映射为输出字段类型,嵌套对象沿数据图继续解析。

概念解释

GraphQL 字段可以带参数,例如 user(id: 123)。在 async-graphql 里这些参数直接写成 Rust 方法参数:标量类型对应 GraphQL 标量,复杂入参用 #[InputObject] 结构体。返回的对象类型若被 #[Object] 标注,客户端再选其内部字段时会再次进入对应 resolver,形成逐层解析。

原理流程

  1. schema 构建期读取 resolver 方法签名,登记参数名、类型与必填性。
  2. 请求解析后,把查询字符串里的参数值反序列化到 Rust 参数类型。
  3. 调用 resolver 拿到返回对象。
  4. 对返回对象的子字段,按查询选择集递归调用对应 resolver。
  5. 叶子字段(标量)直接写入响应 JSON。

代码或图示

use async_graphql::{Object, Result};

struct Query;

#[Object]
impl Query {
    async fn user(&self, id: u64) -> Result<User> {
        // 按 id 查询并返回 User 对象
        Ok(User { id, name: "Ann".into() })
    }
}

struct User { id: u64, name: String }
#[Object]
impl User {
    async fn id(&self) -> u64 { self.id }
    async fn name(&self) -> &str { &self.name }
}

常见误区

  • 把查询过滤条件全塞进一个 JSON 标量参数:失去类型校验,应拆成参数或 InputObject。
  • 返回大对象却未控制选择集:数据库层容易按全字段取数,需要配合 dataloader 与字段裁剪。

追问

  • 必填参数与可选参数在类型上怎么区分?答:T 为必填,Option<T> 为可选;反序列化失败会进入字段错误。
  • 嵌套对象的 resolver 什么时候被调用?答:只有当客户端选择集包含该子字段时才调用,未选择的字段不执行。

04.4.9.3-005 Mutation resolver 与 Query resolver 在写法和语义上有什么区别?

一句话结论

Mutation resolver 写法上同样是 #[Object] 方法,但语义上负责写入与状态变更;客户端一次请求中的多个 Mutation 字段默认按顺序执行,而 Query 字段可并发执行。

概念解释

GraphQL 把有副作用的操作集中在 Mutation 根下,便于审计、权限控制与缓存失效约定。async-graphql 里 Mutation 根结构体与 Query 一样挂派生宏;区别主要在执行模型:规范约定 Mutation 字段串行求值,避免并发写产生竞态。返回值通常是被变更的资源对象,便于客户端立刻刷新本地缓存。

原理流程

  1. 定义 struct Mutation 并 #[Object] 实现写方法。
  2. 方法内完成参数校验、事务写入与结果组装。
  3. 客户端发送 mutation { createUser(...) { id name } }。
  4. 执行器按顺序调用 Mutation 字段,前一个完成后再跑下一个。
  5. 返回变更后的对象,其内部字段再按选择集解析。

代码或图示

use async_graphql::{Object, Result, InputObject};

#[derive(InputObject)]
struct CreateUserInput { name: String, age: Option<i32> }

struct Mutation;

#[Object]
impl Mutation {
    async fn create_user(&self, input: CreateUserInput) -> Result<User> {
        // 落库后返回新用户对象
        Ok(User { id: 1, name: input.name })
    }
}

常见误区

  • 在 Mutation 里做大量只读拼装:只读应放 Query,避免挤占串行执行通道。
  • 以为多个 Mutation 一定并发跑:规范与库实现默认串行,跨字段并发写需要自己拆事务边界。

追问

  • Mutation 失败后事务如何回滚?答:在 resolver 内部用数据库事务包裹写入,返回 Err 时事务回滚;GraphQL 层本身不替你管理数据库事务。
  • 为什么 Mutation 要返回完整资源对象?答:客户端据此更新本地缓存,避免再发一次查询;返回应包含变更后的最新状态。

04.4.9.3-006 Subscription 如何声明一个推送流,方法返回类型有什么约束?

一句话结论

Subscription 根用订阅派生宏标注,方法返回一个实现流 trait(如 Stream)的类型,事件逐个从流中产出并推送给订阅的客户端;底层通常依托 WebSocket 长连接。

概念解释

与一次性返回结果的 Query/Mutation 不同,Subscription 是长生命周期的推送模型:客户端发起订阅后,服务端在事件发生时持续推送消息。Rust 侧需要返回异步流,async-graphql 负责把流事件转换成订阅消息帧。连接断开、流结束或错误产生时订阅关闭。

原理流程

  1. 定义订阅根结构体并挂订阅派生宏。
  2. resolver 方法返回流类型,例如由 tokio::sync::broadcast 或 channel 包装成的 Stream。
  3. 客户端通过 WebSocket 发起带 subscription 操作的连接。
  4. 事件进入流后,库把每个事件序列化为订阅消息推送。
  5. 连接关闭或流终止时清理订阅与监听资源。

代码或图示

use async_graphql::Subscription;
use futures_util::stream::Stream;
use std::pin::Pin;

struct SubscriptionRoot;

#[Subscription]
impl SubscriptionRoot {
    async fn message_added(&self) -> Pin<Box<dyn Stream<Item = String> + Send + 'static>> {
        // 实际项目中由 broadcast/channel 事件流包装而来
        Box::pin(futures_util::stream::empty())
    }
}

常见误区

  • 把 Subscription 当轮询接口用:它解决的是服务端主动推送,客户端拉取仍走 Query。
  • 流里持有阻塞操作:会阻塞整条推送通道,慢消费者要配合背压与丢弃策略。

追问

  • 订阅鉴权在哪里做?答:握手阶段从连接头或上下文解析身份,注入 Data/Context;具体握手钩子以集成包文档为准。
  • 订阅消息会不会积压?答:取决于 channel 容量与背压策略,慢消费会堆积在缓冲层,需要设置容量上限与溢出处理。

04.4.9.3-007 Context 在 resolver 中能读到哪些信息,与 Data 如何分工?

一句话结论

Context<'_> 是单次请求的上下文句柄,可访问请求注册数据、当前字段路径与选择集;Data 是 schema 级全局共享资源,在构建期注册,通过 Context 取出。

概念解释

Context 把一次 GraphQL 执行过程中需要的运行期信息集中起来:从 schema 注册的全局数据(数据库连接池、配置、鉴权身份),到当前字段在查询树中的位置。Data<T> 包装的是构建期注册的共享实例;Context::data::<T>() 负责在请求内把它取出来。两者分工:Data 管「跨请求共享什么」,Context 管「本次执行能访问什么」。

原理流程

  1. Schema::build(...).data(value) 在构建期注册全局实例。
  2. 请求执行时,执行器为每个字段构造 Context,引用同一份注册数据。
  3. resolver 声明 ctx: &Context<'_> 参数即可读取。
  4. ctx.data::<T>() 按类型取注册实例,类型不匹配时返回错误。
  5. 字段路径、选择集等元信息通过 Context 上的方法查询。

代码或图示

use async_graphql::{Object, Context, Data, Result};

struct AppState { db_url: String }

struct Query;

#[Object]
impl Query {
    async fn ping(&self, ctx: &Context<'_>) -> Result<String> {
        let state = ctx.data::<AppState>()?;
        Ok(state.db_url.clone())
    }
}

let schema = Schema::build(Query, EmptyMutation, EmptySubscription)
    .data(Data::new(AppState { db_url: "sqlite://mem".into() }))
    .finish();

常见误区

  • 把每次请求才有的临时数据塞进 Data:Data 是全局共享,请求级状态应放在请求扩展或框架层。
  • 以为 Context 可以跨字段随便可变借用:它是只读句柄,写状态走内部可变性或外部资源。

追问

  • ctx.data::<T>() 取不到类型时返回什么?答:返回错误类型,通常映射为字段错误;具体错误类型以 docs.rs 当前版本为准。
  • 鉴权身份放哪一层?答:框架中间件解析后放进请求扩展,再通过 Data/上下文注入 resolver,避免在每个 resolver 重复解析 header。

04.4.9.3-008 如何用 .data(...) 向 schema 注入连接池或配置,类型注册有什么要求?

一句话结论

构建 schema 时链式调用 .data(...) 注册共享实例,resolver 内用 ctx.data::<T>() 按类型取出;注册与取出必须是同一具体类型,通常用 Arc 共享线程安全实例。

概念解释

GraphQL 库本身不创建业务资源,数据库连接池、缓存客户端、配置等由应用层构建后注入 schema。注册时按类型索引,因此同名包装类型要避免冲突;跨线程共享要求类型满足 Send + Sync。Data 包装与直接注册具体类型的写法在不同版本有差异,需对照 docs.rs 确认。

原理流程

  1. 应用启动时创建连接池、配置等资源。
  2. Schema::build(...).data(resource) 注册进 schema 构建器。
  3. finish() 后 schema 不可变,资源被内部持有。
  4. 各 resolver 通过上下文按类型取回实例使用。
  5. 应用关闭时随资源生命周期释放连接池。

代码或图示

use async_graphql::{Schema, Data, Object};
use std::sync::Arc;

struct Repo { pool: String }
struct Query;
#[Object] impl Query { async fn noop(&self) -> bool { true } }

let schema = Schema::build(Query, EmptyMutation, EmptySubscription)
    .data(Data::new(Arc::new(Repo { pool: "pool".into() })))
    .finish();

常见误区

  • 注册 &'static 之外的引用导致生命周期报错:共享实例要拥有所有权并满足 Send + Sync。
  • 把两个相同类型的资源都注册后无法区分:用 newtype 包装区分类型标识。

追问

  • 注册资源需要克隆连接池吗?答:连接池本身可克隆内部句柄,注入一次后 resolver 取到共享 Arc 或池克隆即可,不要在 Data 里放裸连接。
  • 不同环境(测试/生产)如何替换?答:在组装 schema 的位置注入不同实现,resolver 只依赖抽象接口或具体配置,便于测试替身替换。

04.4.9.3-009 #[InputObject] 与 #[Object] 在用途上有何区别,输入类型能否被输出?

一句话结论

#[InputObject] 标记作为参数传入的输入结构体,#[Object] 标记作为响应返回的输出对象;GraphQL 类型系统要求输入类型与输出类型分离,二者不能混用。

概念解释

GraphQL 有两套类型体系:输出类型(Object)用于响应,输入类型(InputObject)用于字段参数与 Mutation 入参。async-graphql 用不同派生宏分别生成对应元数据。实践中常为同一概念建两个 DTO:写入入参用 InputObject,返回资源用 Object,内部再做字段映射。标量、枚举、Option、Vec 可以在输入输出两侧复用。

原理流程

  1. 定义入参结构体并 #[derive(InputObject)],字段成为输入字段。
  2. 在 resolver 参数位置使用该类型,库做反序列化与必填校验。
  3. 定义响应结构体 #[Object],方法作为输出字段。
  4. 业务层把输入 DTO 转换为领域模型,再组装输出 DTO。
  5. 校验失败时参数反序列化错误进入 GraphQL 错误响应。

代码或图示

use async_graphql::{InputObject, Object, Result};

#[derive(InputObject)]
struct SignupInput { email: String, password: String }

struct Profile { id: u64, email: String }

#[Object]
impl Profile {
    async fn id(&self) -> u64 { self.id }
    async fn email(&self) -> &str { &self.email }
}

struct Mutation;
#[Object]
impl Mutation {
    async fn signup(&self, input: SignupInput) -> Result<Profile> {
        Ok(Profile { id: 1, email: input.email })
    }
}

常见误区

  • 复用同一个结构体既当入参又当响应:GraphQL 规范不允许输入类型直接出现在输出位置,派生宏也会约束。
  • 在 InputObject 上写业务方法:输入类型只承载数据,逻辑放服务层。

追问

  • 输入嵌套对象如何声明?答:字段类型为另一个 #[InputObject] 结构体即可,嵌套层级由 schema 校验。
  • 入参校验在哪一层做?答:反序列化做类型与必填检查,业务规则在 resolver 或服务层校验;通用校验库的职责与 04.4.9.2 一致。

04.4.9.3-010 如何为库没有覆盖的类型实现自定义 Scalar?

一句话结论

对需要跨网络传输但默认没有标量映射的类型,实现标量 trait 并在字段上标注;内部把值编解码为 JSON/字符串,类型名与解析规则在 schema 中显式声明。

概念解释

GraphQL 内置标量有限(Int、Float、String、Boolean、ID)。业务中的 UUID、Decimal、日期等类型,库通常通过 feature 提供标量实现;未覆盖的类型需要自定义标量:序列化时转成标量字面量,反序列化时校验并还原。自定义标量要在 schema 中暴露明确的类型名与格式说明,否则客户端难以对接。

原理流程

  1. 确认该类型是否已有 feature 提供的现成标量实现,避免重复造轮子。
  2. 实现标量 trait:序列化写出标量值,反序列化校验输入并构造内部类型。
  3. 在 Object/InputObject 字段类型上使用该自定义标量类型。
  4. schema 内省会暴露该标量的名称与描述。
  5. 客户端按约定格式传值,服务端解析失败时返回字段错误。

代码或图示

use async_graphql::{Scalar, Value, Context, Result};

// 待确认:自定义标量 trait 的确切方法签名以 docs.rs/async-graphql 当前版本为准
#[derive(Scalar, Clone, Debug)]
struct HexId(String);

impl HexId {
    fn to_value(&self) -> Value { Value::String(self.0.clone()) }
}

常见误区

  • 把结构化对象塞进自定义标量:应建模为 Object/InputObject,标量只承载叶子值。
  • 反序列化时不做格式校验就直接构造类型:非法输入会在后续环节才暴露,应在标量层拒绝。

追问

  • UUID、Decimal 这类常用类型要不要手写标量?答:先查 async-graphql 的对应 feature 是否内置支持;内置实现经过 schema 与序列化校验,优先使用。
  • 自定义标量如何写进文档?答:在类型上挂描述属性,内省与 playground 可见;对外契约文档需注明格式(如 UUID v4 字符串)。

04.4.9.3-011 GraphQL 枚举在 Rust 侧如何定义,输入与输出能否共用?

一句话结论

枚举用枚举派生宏映射为 GraphQL 枚举类型,变体名转为枚举值;枚举既可作为输出字段类型,也可作为输入参数类型,是少数允许输入输出两侧共用的类型。

概念解释

Rust 枚举天然适合映射 GraphQL enum:每个变体对应一个枚举字面量。async-graphql 派生宏生成序列化/反序列化与 schema 元数据。变体可通过属性改名为对外枚举值。枚举作为入参时,客户端只能传约定的字面量;新增变体属于兼容性变更,需要按版本演进策略评估。

原理流程

  1. 定义 Rust 枚举并挂枚举派生宏。
  2. 编译期为每个变体生成对外枚举值(默认变体名,可改名)。
  3. 输出时把内部枚举序列化为字面量字符串。
  4. 输入时校验字面量是否匹配已知变体,未知值进入错误。
  5. 在 Object 字段与 InputObject 字段中复用该枚举类型。

代码或图示

use async_graphql::{Enum, Object, InputObject};

#[derive(Enum, Copy, Clone, Eq, PartialEq)]
enum OrderStatus { Pending, Paid, Shipped, Done }

struct Order { status: OrderStatus }

#[Object]
impl Order {
    async fn status(&self) -> OrderStatus { self.status }
}

#[derive(InputObject)]
struct Filter { status: Option<OrderStatus> }

常见误区

  • 枚举携带数据再当 GraphQL 枚举用:带字段的复杂变体应建模为对象/联合类型,纯枚举只能是无数据变体。
  • 对外枚举值用大小写不符的裸变体名:按客户端约定用属性改名,避免蛇形/驼峰混乱。

追问

  • 旧客户端传了服务端新增的枚举值会怎样?答:反序列化校验失败,返回字段错误;这也是枚举新增值需要兼容策略的原因,详见本章版本演进部分。
  • 枚举能否表示「未知兜底」?答:Rust 侧可保留 Unknown 变体做宽松解析,但会掩盖契约错误,对外接口不建议默认放开。

04.4.9.3-012 resolver 抛错时 FieldError 如何构造,错误如何进入响应?

一句话结论

resolver 返回 Err(FieldError::new(...)),错误被执行器收集进响应的 errors 数组;FieldError 可携带消息、扩展信息与对应的字段路径,不影响其他独立字段返回结果。

概念解释

GraphQL 响应分 data 与 errors 两段:字段失败不代表整个请求失败,无依赖的字段仍可返回。FieldError 是 resolver 层的错误载体,区别于 HTTP 层错误。业务错误应给出稳定错误码与可读消息,避免把内部异常栈直接抛给客户端。错误实现 Into<FieldError> 后可在 Result 中直接返回。

原理流程

  1. resolver 内校验或调用外部资源失败,构造 FieldError。
  2. 返回 Err 后执行器记录字段路径与错误信息。
  3. 其他无依赖字段继续执行,结果放入 data。
  4. 失败字段在 data 中对应位置为 null,错误汇总到 errors。
  5. 框架层把 GraphQL 响应序列化为 HTTP 200 响应体(错误不在 HTTP 状态码层表达,需另定约定)。

代码或图示

use async_graphql::{Object, FieldError, Result, ErrorExtension};

struct Query;

#[Object]
impl Query {
    async fn divide(&self, a: i32, b: i32) -> Result<i32> {
        if b == 0 {
            return Err(FieldError::new("division by zero")
                .with_extension("code", "BAD_REQUEST"));
        }
        Ok(a / b)
    }
}

常见误区

  • 把 FieldError 映射成 HTTP 500:GraphQL 错误通常在 200 响应体的 errors 中表达;框架层要另定错误码到状态码的策略。
  • 错误消息里拼接数据库 SQL、连接串等内部信息:泄漏实现细节,对外消息要脱敏。

追问

  • 错误扩展信息支持哪些类型?答:extensions 通常放键值对,可携带错误码、字段名等结构化信息;具体值类型以 docs.rs 当前版本为准。
  • 业务错误与框架错误如何分层?答:领域错误在服务层定义,转成稳定 FieldError 与错误码;库/框架原始错误记录日志后包装,不直接透传。

04.4.9.3-013 如何给 GraphQL 错误附稳定错误码与扩展字段,便于前端处理?

一句话结论

在 FieldError 上追加扩展信息(如 code、field),前端按 code 分支处理;响应体的 extensions 块承载机器可读信息,message 只做人读展示。

概念解释

裸错误消息会随文案调整而变化,前端无法稳定依赖。工程上约定:每个业务错误有稳定错误码(字符串或枚举),消息面向人读,扩展字段面向机器。async-graphql 的错误扩展机制允许挂键值对;日志侧再记录完整内部原因。错误码体系应与 REST 接口的错误码规范保持一致。

原理流程

  1. 在领域层定义错误类型与对应稳定错误码。
  2. resolver 构造 FieldError 时填入消息与扩展(code、定位信息)。
  3. 执行器把扩展随错误一起写入响应 errors[].extensions。
  4. 前端按 code 决定提示、跳转或重试,不解析文案。
  5. 服务端日志保留内部堆栈与请求 ID,便于追溯。

代码或图示

use async_graphql::{FieldError, Result};

fn not_found(id: u64) -> FieldError {
    FieldError::new(format!("user {id} not found"))
        .with_extension("code", "USER_NOT_FOUND")
}

// resolver 中:Err(not_found(id))

常见误区

  • 用 HTTP 状态码代替 GraphQL 错误码:GraphQL 一次请求可包含多个字段错误,统一状态码无法表达逐字段失败。
  • 错误码随接口迭代随意改名:错误码是对外契约,废弃需走版本演进流程。

追问

  • 扩展里能不能放敏感数据?答:不能,扩展随响应下发;敏感细节只进服务端日志,响应中保留请求 ID 即可。
  • 批量字段部分失败如何定位?答:错误携带字段路径,扩展可带业务标识(如入参 id),前端按路径回滚对应 UI 状态。

04.4.9.3-014 鉴权身份如何从请求头传递到 resolver 的上下文?

一句话结论

框架层中间件解析 token 得到身份,放进请求扩展或 schema 注册数据;resolver 从 Context 取出身份做权限判断,不在 resolver 内重复解析原始 header。

概念解释

GraphQL 端点复用 Web 框架的鉴权中间件:中间件在进入 GraphQL 执行前完成认证,把身份对象挂到请求上下文。schema 构建期注册的全局数据与请求级扩展通过 Context 暴露给 resolver。权限粒度可分两层:字段级守卫控制能否查询,resolver 内再校验资源归属。

原理流程

  1. 客户端在 HTTP 头携带凭证(如 Authorization)。
  2. 框架中间件校验凭证,构造身份对象写入请求扩展。
  3. GraphQL 集成层把身份注入执行上下文。
  4. resolver 通过 ctx.data::<CurrentUser>() 取身份。
  5. 字段守卫或 resolver 内判断角色/资源归属,拒绝时返回 FieldError。

代码或图示

use async_graphql::{Object, Context, Result};

struct CurrentUser { id: u64, role: String }

struct Query;

#[Object]
impl Query {
    async fn me(&self, ctx: &Context<'_>) -> Result<String> {
        let user = ctx.data::<CurrentUser>()?;
        if user.role != "admin" {
            return Err(async_graphql::FieldError::new("forbidden")
                .with_extension("code", "FORBIDDEN"));
        }
        Ok(user.id.to_string())
    }
}

常见误区

  • 在每个 resolver 里手写 header 解析:重复且容易漏校验,应集中在中间件层。
  • 只在 Query 入口鉴权,嵌套对象 resolver 不校验归属:子对象可能被直接查询,需逐资源校验。

追问

  • 未登录访问如何表达?答:中间件可直接拒绝请求返回 401;进入执行后发现缺身份则在 resolver 返回未认证错误。
  • 字段级权限怎么统一收口?答:用字段守卫或上下文角色表批量控制;具体守卫宏/ trait 以 docs.rs 当前版本为准。

04.4.9.3-015 什么是 GraphQL 的 N+1 问题,dataloader 如何批量消除?

一句话结论

N+1 指解析一批对象时,每个对象各自发起一次查询,形成 1 次主查询加 N 次关联查询;dataloader 把同一 tick 内的批量键收集起来,合并成一次批量查询回填结果。

概念解释

GraphQL 嵌套字段天然容易触发 N+1:先取 100 个用户,每个用户的 orders 字段都查一次订单表。dataloader 模式由 loader、调度与缓存三部分组成:resolver 不直接查库,而是把键交给 loader;loader 等待一小段时间窗口,收集这批键后批量查询,再按键分发结果。async-graphql 内置 dataloader 集成,配合 Loader trait 实现批量取数。

原理流程

  1. 实现 Loader trait:load 接收一批键,批量查库,返回键到值的映射。
  2. 用 DataLoader 包装 loader,配置批大小与缓存,注册进 schema Data。
  3. 字段 resolver 调用 loader 按键加载,触发单个 Promise/任务。
  4. 调度器在当前执行轮次收集所有待加载键,合并一次批量查询。
  5. 结果按键回填给各个 resolver,缓存可避免同请求内重复加载。

代码或图示

use async_graphql::dataloader::{DataLoader, Loader};
use std::collections::HashMap;
use async_trait::async_trait;

struct UserLoader;

#[async_trait]
impl Loader<u64> for UserLoader {
    type Value = User;
    type Error = async_graphql::Error;

    async fn load(&self, keys: &[u64]) -> Result<HashMap<u64, User>, Self::Error> {
        // 一次 WHERE id IN (...) 批量取回,而不是循环单查
        let map = keys.iter().map(|&k| (k, User { id: k, name: "Ann".into() })).collect();
        Ok(map)
    }
}

// 注册:.data(DataLoader::new(UserLoader, tokio::spawn).build())

常见误区

  • loader 内部又按键循环单查:只是套了一层壳,没有真正批量。
  • 缓存跨请求保留导致脏数据:dataloader 缓存粒度与生命周期要按业务选择,易变数据关掉缓存。

追问

  • 批量查询缺键时如何处理?答:返回映射中缺失的键对应 None,resolver 输出 null;不要为缺键报错中断整批。
  • dataloader 缓存层级有哪些?答:通常有请求内缓存(避免同批重复)与跨请求缓存;实现细节与开关以 docs.rs 当前版本为准。

04.4.9.3-016 实现 Loader 时批处理函数的职责边界是什么,错误如何在批量内传播?

一句话结论

Loader::load 只负责「给一批键,返回这批键到值的映射」,不做单个字段的业务判断;批量内部分键失败应体现在值缺失或错误映射上,整批失败才返回 Err。

概念解释

批量 loader 的关键是把取数与业务语义分开:数据访问层按集合查询,组装 HashMap<Key, Value>。部分键无对应数据属于正常情况(返回 None 或缺映射);只有批量查询本身不可用(连接失败、语句错误)才整体返回错误。错误传播粒度要提前约定:是整批失败、按键失败还是缺键给默认值。

原理流程

  1. 收到去重后的键切片。
  2. 用一条批量语句(IN 查询、批量 mget 等)取回数据集。
  3. 遍历数据集填入映射,未命中的键留空。
  4. 整批异常(连接、超时)转为 loader 错误返回。
  5. 上层 resolver 按取到的值组装对象,缺键输出 null 或业务错误。

代码或图示

use std::collections::HashMap;

// 伪代码:批量从仓储层取数
async fn load_users(keys: &[u64]) -> HashMap<u64, User> {
    let rows = repo.find_by_ids(keys).await.unwrap_or_default();
    rows.into_iter().map(|u| (u.id, u)).collect()
}

常见误区

  • 批处理函数里混权限判断:loader 是共享取数组件,权限在 resolver 层结合身份判断。
  • 批量失败时把部分已取回的数据丢弃:应区分「查询整体失败」与「部分键未命中」。

追问

  • 键需要去重吗?答:loader 调度层通常会合并重复键;实现 load 时仍应假设输入可能有重复并以映射去重。
  • 批量大小需要限制吗?答:需要,超大 IN 列表会拖垮数据库;loader 可配置批大小,超过时分批。

04.4.9.3-017 如何把 async-graphql schema 挂到 axum 路由上?

一句话结论

使用 async-graphql-axum 集成包,把 GraphQL 处理器与 schema 注册到 axum 路由;schema 作为共享状态或处理器内部持有,监听单个 POST(GET 用于 playground/查询)端点。

概念解释

GraphQL 服务端对外是一个 HTTP 端点:客户端把查询放进请求体 POST 过来。集成包把 schema 包装成 axum 可挂载的 handler,负责解析请求 JSON、执行查询、返回 GraphQL 响应。schema 构建一次后共享;鉴权、CORS、body 限制等仍由 axum 中间件层处理。

原理流程

  1. 引入 async-graphql-axum,构建共享 schema。
  2. 用集成包提供的 GraphQL::new(schema) 构造处理器。
  3. 在 axum Router 上注册该处理器到路径(如 /graphql)。
  4. 框架中间件先完成鉴权、跨域等横切处理。
  5. 请求进入库后解析与执行查询,返回 data/errors 响应体。

代码或图示

use axum::Router;
use async_graphql::{Schema, EmptyMutation, EmptySubscription};
use async_graphql_axum::GraphQL;

struct Query;
// #[Object] impl Query { ... }

let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();

let app = Router::new()
    .route("/graphql", axum::routing::post(GraphQL::new(schema.clone())));

常见误区

  • 每个请求重建 schema:类型元数据与注册资源被重复构造,内存与启动成本上升。
  • 把 GraphQL 处理器当普通 REST 路由做方法级拆分:查询形状在请求体里,路径通常保持单一端点。

追问

  • schema 如何放入 axum State?答:Schema 可克隆内部句柄,注入 State 后 handler 取出传给 GraphQL::new;状态注入方式与 axum 章节约定一致。
  • 集成包版本与 async-graphql 要对齐吗?答:要,集成包与主库版本通常配套;具体兼容范围以 docs.rs/crates.io 当前版本为准。

04.4.9.3-018 如何挂载 GraphiQL 或 Playground 供浏览器调试?

一句话结论

集成包提供内置 IDE 处理器,挂到独立 GET 路径后在浏览器打开即可发送查询、查看内省 schema;生产环境通常按环境变量关闭或限制访问。

概念解释

开发期需要可视化工具拼装查询、查看类型文档与历史请求。async-graphql 生态提供 GraphiQL/playground 类型处理器,它本质是一个返回 HTML 页面的 GET handler,页面内通过同端点发 GraphQL 请求。生产环境暴露 playground 会泄露 schema 细节,应默认关闭或加鉴权与内网限制。

原理流程

  1. 开发模式下把 IDE 处理器挂到 /graphiql 等路径。
  2. 浏览器打开页面,工具通过内省查询拉取 schema 类型。
  3. 开发者编写查询并发送,响应与错误在页面展示。
  4. 生产构建按配置跳过该路由或加访问控制。
  5. 内省本身也可通过 schema 配置关闭,避免对外暴露完整类型。

代码或图示

// 待确认:IDE 处理器类型名与挂载方式以 docs.rs/async-graphql-axum 当前版本为准
use axum::Router;

let app = Router::new()
    // .route("/graphql", post(GraphQL::new(schema.clone())))
    // .route("/graphiql", get(GraphiQL::new("/graphql")))
    ;

常见误区

  • 生产环境遗留 playground 可匿名访问:泄漏接口结构与字段细节。
  • 内省全开但错误信息回传内部堆栈:调试便利与信息保密要分环境控制。

追问

  • 关闭内省后 IDE 还能用吗?答:不能自动补全与类型提示,只能手写查询;关闭内省是常见的生产加固手段。
  • playground 与生产 API 必须同端点吗?答:页面可指向任意 GraphQL 端点路径;跨域时需框架层放行 CORS。

04.4.9.3-019 Subscription 在 HTTP 层依托什么传输,握手与消息帧如何组织?

一句话结论

订阅走 WebSocket 长连接,按 GraphQL over WS 子协议交换连接初始化、订阅、数据与停止消息;集成库负责协议帧解析与流到消息的转换。

概念解释

普通 HTTP 请求-响应无法承载持续推送,订阅必须升级为长连接。WebSocket 子协议约定消息类型:连接初始化、订阅注册、数据推送、错误、停止与关闭。async-graphql 与框架集成层处理握手、帧编解码与生命周期;服务端把 Rust 流事件逐条转成数据帧。连接断开后订阅资源需回收。

原理流程

  1. 客户端发起 WebSocket 握手,携带认证信息与子协议。
  2. 服务端校验身份,完成连接初始化握手。
  3. 客户端发送订阅消息,携带查询字符串与变量。
  4. 服务端执行订阅 resolver 得到流,事件到达时推送数据帧。
  5. 客户端停止订阅或连接断开,服务端取消流并清理监听。

代码或图示

客户端 ── WS 握手 (Authorization, graphql-ws 子协议) ──→ 服务端
客户端 ── connection_init ─────────────────────────→ 服务端
服务端 ── connection_ack ─────────────────────────→ 客户端
客户端 ── subscribe { query, variables } ─────────→ 服务端
服务端 ── next { data } / error ──────────────────→ 客户端
客户端 ── complete / close ──────────────────────→ 服务端清理

常见误区

  • 用短轮询模拟订阅:无法达到推送实时性,也浪费请求量。
  • 连接断开后不取消后台流:监听与 channel 句柄泄漏,事件继续往死连接推。

追问

  • 认证信息放在 WebSocket 握手哪一层?答:通常在握手 HTTP 头或初始化消息载荷中;具体约定以集成包实现为准。
  • 多实例下订阅如何跨节点推送?答:本地流只收本节点事件,跨节点事件需经消息队列/发布订阅中转后再推给本地连接。

04.4.9.3-020 如何给 schema 配置查询复杂度与深度限制,防止恶意查询打爆服务?

一句话结论

通过 schema 的复杂度上限与深度上限配置,对字段权重与嵌套层数求值;超限查询在执行前拒绝,避免深层嵌套或广扇出查询拖垮数据库与服务。

概念解释

GraphQL 开放字段组合后,恶意或疏忽的查询可以构造超大扇出(一次取成百上千条列表)或深层递归嵌套。复杂度限制给每个字段设定成本权重,累加超过阈值即拒绝;深度限制约束嵌套层级。async-graphql 提供 complexity/depth 相关配置,字段可标注自身权重。限制要在查询执行前、在数据库访问之前生效。

原理流程

  1. 为高成本字段(列表、关联查询)设置复杂度权重。
  2. schema 配置全局复杂度上限与深度上限。
  3. 查询解析后先做静态成本评估:按选择集累加权重、统计嵌套深度。
  4. 超限直接拒绝,返回错误,不进入 resolver 执行。
  5. 正常查询按评估结果放行,运行期再配合超时与限流兜底。

代码或图示

use async_graphql::Schema;

// 待确认:配置方法名(复杂度/深度上限)以 docs.rs/async-graphql 当前版本为准
let schema = Schema::build(Query, EmptyMutation, EmptySubscription)
    // .limit_complexity(1000)
    // .limit_depth(10)
    .finish();

常见误区

  • 只限制深度不限制复杂度:浅层但超大扇出的查询同样可以打爆服务。
  • 复杂度在 resolver 内才计算:数据库已经被访问,限制失去前置防护意义。

追问

  • 列表字段复杂度如何随参数变化?答:可按分页大小动态计算权重,参数越大权重越高;动态权重写法以库文档为准。
  • 限制阈值如何定?答:压测典型查询的成本与耗时,结合单请求预算设定;上线后观测超限拒绝率再调整。

04.4.9.3-021 单次 HTTP 请求内的批量查询(batching)与接口限流如何设计?

一句话结论

批量查询指一次请求携带多个操作或合并重复字段查询,降低往返次数;限流则按客户端身份、查询成本与频率在框架层或库扩展层拒绝超额请求,两者都要在保护服务的前提下设计。

概念解释

GraphQL 的 batching 分两层:传输层把多个查询打包进一次 HTTP 请求;执行层由 dataloader 合并相同键的批量取数。限流要覆盖 QPS、并发查询数与单次查询复杂度,避免单个大查询占满连接池。Rust 侧限流常复用 tower 层或中间件能力,按身份维度计数,超限返回约定错误。

原理流程

  1. 请求进入框架层,先按身份提取限流键(用户、租户、IP)。
  2. 限流中间件判断频率与并发是否超阈值。
  3. 通过后进入 GraphQL 执行,dataloader 在执行轮次内合并批量取数。
  4. 单次查询再叠加复杂度/深度评估作为第二道闸门。
  5. 超限请求在访问数据库前被拒绝,记录限流指标。

代码或图示

请求 → 鉴权 → 限流(QPS/并发) → 复杂度评估 → 执行器 → dataloader 批量取数 → 响应

常见误区

  • 只做全局限流不区分身份:被限流的低权用户会误伤正常高权用户。
  • 为了 batching 放宽超时:批量请求持有资源更久,反而放大雪崩风险。

追问

  • 限流计数存哪?答:单实例可用本地计数,多实例用 Redis 计数;窗口算法与 Redis 章节的限流方案一致。
  • 批量查询占连接时间长怎么办?答:限制批大小与总复杂度,设置独立超时,慢查询单独降级。

04.4.9.3-022 GraphQL 响应字段能否做服务端缓存,缓存键如何设计?

一句话结论

只读字段可加缓存(库提供的字段缓存或应用层缓存),缓存键必须包含对象类型、标识与所取字段;变更后按对象失效,避免跨请求返回脏数据。

概念解释

GraphQL 天然按字段取数,重复请求相同对象是常见场景。服务端缓存可以在 resolver 之前命中,减少数据库访问。缓存键要能定位「哪个对象的哪组数据」,通常由类型名加主键构成;字段选择集不同时缓存粒度要重新评估。写操作通过 Mutation 主动失效对应对象缓存。

原理流程

  1. resolver 取数前先查缓存键(类型 + 主键 + 缓存版本)。
  2. 命中则直接组装字段;未命中访问数据源并回填缓存。
  3. 设置 TTL 与权重,防止热点缓存无限膨胀。
  4. Mutation 变更后删除或更新对应对象缓存。
  5. 多实例部署时通过失效广播通知各节点本地缓存(与多级缓存章节衔接)。

代码或图示

// 应用层伪代码:键设计为 "user:{id}:v1"
async fn cached_user(id: u64, cache: &impl Cache) -> Option<User> {
    if let Some(u) = cache.get(&format!("user:{id}:v1")).await? {
        return Some(u);
    }
    let user = repo.find(id).await?;
    cache.set(format!("user:{id}:v1"), &user).await;
    Some(user)
}

常见误区

  • 缓存可变状态却不主动失效:只能靠 TTL 兜底,窗口内数据不一致。
  • 缓存键不含字段版本:DTO 演进加字段后旧缓存反序列化出错,需带版本前缀。

追问

  • 列表结果要不要缓存?答:可缓存但失效粒度粗,过滤条件组合多;优先缓存单对象,列表配合短 TTL 与主动刷新。
  • 字段缓存与 dataloader 缓存如何分层?答:dataloader 缓存偏请求内批量合并,服务端缓存跨请求;两者生命周期与失效策略分开管理。

04.4.9.3-023 库的 Extension/中间件机制能在执行周期的哪些挂钩点做事情?

一句话结论

扩展机制可在请求开始、字段解析前后、错误发生与请求结束等挂钩点介入,用于埋点日志、耗时统计、鉴权拦截与响应改写;具体挂钩 trait 以库文档为准。

概念解释

GraphQL 执行有明确生命周期:解析查询、校验 schema、进入操作、逐字段解析、组装响应。扩展(Extension)在这些节点插入横切逻辑,避免把日志、指标代码散落到每个 resolver。Rust 库通过 trait 提供钩子方法,默认实现为空,按需覆写。跨切面关注点(追踪、错误记录、权限)优先走扩展而不是复制到业务 resolver。

原理流程

  1. schema 构建时注册扩展实例。
  2. 请求进入后触发开始钩子,初始化追踪上下文。
  3. 每个字段解析前后触发对应钩子,记录耗时与字段路径。
  4. resolver 返回错误时触发错误钩子,补充日志与脱敏。
  5. 请求结束钩子汇总指标,输出响应。

代码或图示

// 待确认:扩展 trait 名与钩子方法签名以 docs.rs/async-graphql 当前版本为准
// 典型做法:实现扩展 trait,覆写请求开始/字段前后/结束钩子
// .extension(MyTraceExtension)

常见误区

  • 在扩展钩子里做阻塞重计算:挂钩点在执行路径上,阻塞会拖慢整条请求。
  • 把业务校验写进通用扩展:业务规则与身份上下文相关,应留在 resolver 或服务层。

追问

  • 扩展与 Web 框架中间件如何分工?答:框架中间件管 HTTP 层(头、CORS、限流),GraphQL 扩展管执行层(字段级追踪、错误)。
  • 如何给字段耗时打标签?答:在字段前后钩子记录字段路径与耗时,接入 tracing/OpenTelemetry,与可观测性章节衔接。

04.4.9.3-024 生产环境如何关闭或限制 schema 内省(introspection)?

一句话结论

通过 schema 配置关闭内省查询,使客户端无法通过 __schema/__type 拉取完整类型;开发环境保留内省供 IDE 使用,生产环境按安全基线关闭或加访问控制。

概念解释

内省是 GraphQL 的元查询能力,允许客户端读取服务端暴露的全部类型、字段与文档。便利调试的同时,也把接口结构完整暴露给未授权调用方。关闭内省后,已知查询仍可执行,但工具无法自动发现 schema。是否关闭需结合内部系统与对外 API 的安全要求权衡。

原理流程

  1. 开发环境开启内省,IDE 可补全与查看文档。
  2. 生产构建读取环境配置,在 schema 构建期关闭内省。
  3. 客户端发送 __schema 类查询时被拒绝或返回空元信息。
  4. 业务字段查询不受影响。
  5. 对外契约文档另由 SDL/OpenAPI 等受控渠道提供。

代码或图示

// 待确认:关闭内省的配置项名以 docs.rs/async-graphql 当前版本为准
// 常见做法:Schema::build(...).disable_introspection().finish()

常见误区

  • 以为关闭内省就等于接口安全:字段越权、注入、限流问题仍需独立防护。
  • 生产环境为方便排查长期保留内省:扩大信息暴露面。

追问

  • 关闭内省后前端如何拿到类型?答:构建期导出 SDL 交给前端生成类型;SDL 是受控产物,不依赖运行时内省。
  • 内部管理后台要不要关闭?答:按访问面决定,内网可信环境可保留,对外网关必须关闭或加鉴权。

04.4.9.3-025 列表分页在 GraphQL 里有哪些模式,relay 风格 Connection 解决什么问题?

一句话结论

分页常见 offset/页码游标与 relay Connection(edges/node/PageInfo)两类;Connection 用不透明游标定位条目,适合大偏移量与稳定排序,避免 offset 深翻页的性能与重复数据问题。

概念解释

REST 常用 page/size,GraphQL 里列表字段同样可带分页参数。relay 风格 Connection 把返回组织成 edges(含游标与节点)加 pageInfo(hasNextPage/endCursor),游标编码定位键。它解决的问题:深 offset 扫描成本高、新增/删除导致条目错位重复。Rust 侧需要实现游标编码(通常编码排序键,不暴露数据库物理偏移)。

原理流程

  1. 列表字段接收 first/after(或 last/before)参数。
  2. 服务端按游标解析出排序键,用键范围查询而不是 OFFSET。
  3. 取回多一条判断 hasNextPage,生成每条边的游标。
  4. 返回 edges 与 pageInfo。
  5. 客户端沿 endCursor 翻下一页。

代码或图示

orders(first: 20, after: "eyJpZCI6MTAwfQ==") {
  edges { cursor node { id createdAt } }
  pageInfo { hasNextPage endCursor }
}

常见误区

  • 游标直接暴露数据库自增 id:排序变化后游标错位,应编码稳定排序键组合。
  • 深翻页用大 offset:数据库扫描前 N 行成本高,游标分页要走键范围。

追问

  • 分页大小要不要设上限?答:必须设,防止一次拉全量;上限在参数校验层拒绝超大 first。
  • 总条数怎么返回?答:Connection 可不返回总数(避免全表 count);确需总数时单独字段并接受其成本。

04.4.9.3-026 GraphQL 字段的并发执行模型是怎样的,字段间依赖如何处理?

一句话结论

同一层无依赖的字段可并发解析,存在依赖关系的字段按先后顺序等待;执行器按选择集分层调度,resolver 是异步任务,并发度受运行时与批量加载器约束。

概念解释

GraphQL 执行把查询树按层级展开:同一对象上的多个独立字段互不等待,可并发跑;嵌套字段在父对象解析后再调度。Rust 异步运行时负责任务调度,dataloader 把同轮次的批量键合并。理解并发模型有助于判断哪些查询会并行访问数据库、哪里需要批量合并,避免误以为所有字段串行或全部并行。

原理流程

  1. 执行器解析查询树,按对象层级划分调度批次。
  2. 同批次无依赖字段并发启动 resolver 任务。
  3. 字段返回后,其嵌套子字段进入下一批次调度。
  4. dataloader 在批次内收集键,合并批量查询。
  5. 所有叶子字段返回后组装响应。

代码或图示

Query.user { name orders { total } }
批次1: 解析 user
批次2: 并发解析 name 与 orders
批次3: 解析 orders 内各节点字段

常见误区

  • 以为 Mutation 字段也并发:规范约定 Mutation 串行求值,避免并发写竞态。
  • resolver 内做阻塞调用:会占住 worker 线程,拖慢同批次其他字段。

追问

  • 并发度受什么限制?答:Tokio 运行时 worker 数、连接池大小与 dataloader 批大小;数据库连接池是常见瓶颈。
  • 字段间有数据依赖怎么办?答:在同一 resolver 内先取依赖数据再组装,不要指望执行器跨字段传递中间状态。

04.4.9.3-027 如何导出或查看服务端 schema 的 SDL,内省查询长什么样?

一句话结论

可通过库提供的 SDL 导出方法生成 schema 定义文本,或发送内省查询由工具拉取类型;SDL 是契约产物,应纳入版本管理供前端类型生成与评审。

概念解释

SDL(Schema Definition Language)是 GraphQL schema 的文本表达:类型、字段、参数、枚举与文档注释。服务端从 Rust 类型推导出 schema 后,可导出 SDL 文件,作为前后端契约的单一事实源。内省查询是一段特殊 GraphQL 查询,请求 __schema 元信息,工具据此重建 SDL。变更评审时对比 SDL 差异即可判断是否破坏兼容。

原理流程

  1. 应用启动或构建脚本中调用 schema 的 SDL 导出方法。
  2. 输出 .graphql 文件入库,供前端代码生成消费。
  3. 开发期 IDE 向内省端点发送元查询,拉取类型补全。
  4. 接口变更后重新导出 SDL,评审 diff。
  5. 契约测试对照 SDL 校验客户端查询是否仍合法。

代码或图示

# 导出的 SDL 片段示例
type User {
  id: ID!
  name: String!
  orders(first: Int): [Order!]!
}

常见误区

  • 手工维护一份 SDL 与服务端脱节:以服务端推导为准自动生成,避免双写不一致。
  • 把 SDL 当运行时配置:它是产物,运行时 schema 仍由 Rust 类型与派生宏决定。

追问

  • SDL 里的文档注释从哪来?答:在 Rust 类型/字段上挂文档属性,库导出时带入;具体属性写法以 docs.rs 为准。
  • 前端类型如何从 SDL 生成?答:用 GraphQL 代码生成工具把 SDL 转 TypeScript 类型;生成产物与 SDL 版本绑定。

04.4.9.3-028 resolver 的 Result<T, E> 中,业务错误如何转成 FieldError?

一句话结论

resolver 返回 Result<T, E>,错误类型通过 Into<FieldError> 转换;领域错误类型实现转换后,在 resolver 内直接 ? 传播,由执行器包装成 GraphQL 字段错误。

概念解释

业务层通常定义自己的错误枚举(thiserror 风格),直接暴露给 GraphQL 不合适。约定领域错误实现到 FieldError 的转换:映射稳定错误码、消息与扩展信息。resolver 内用 ? 让错误沿调用栈冒泡,执行器统一收集。这样业务代码保持领域语义,对外错误结构由转换层控制。

原理流程

  1. 领域层定义错误枚举与消息、错误码。
  2. 实现 From<DomainError> for FieldError,补扩展信息。
  3. resolver 返回 Result<User, DomainError>,内部 ? 传播。
  4. 执行器调用转换,得到 FieldError 进入错误数组。
  5. 原始内部错误写入日志,响应只带脱敏信息。

代码或图示

use async_graphql::{FieldError, Result};
use thiserror::Error;

#[derive(Error, Debug)]
enum DomainError {
    #[error("not found: {0}")]
    NotFound(u64),
}

impl From<DomainError> for FieldError {
    fn from(e: DomainError) -> Self {
        FieldError::new(e.to_string()).with_extension("code", "NOT_FOUND")
    }
}

async fn get_user(id: u64) -> Result<User, DomainError> {
    Err(DomainError::NotFound(id))
}

常见误区

  • 在 From 转换里吞掉原始错误:日志拿不到内部原因,应先记录再包装。
  • 直接把数据库错误类型透传给客户端:泄漏 SQL 与表结构信息。

追问

  • ? 跨层传播时错误类型怎么统一?答:在服务层定义统一领域错误,底层错误转换进领域错误,再由领域错误转 FieldError。
  • 错误消息要国际化吗?答:响应消息可按语言协商返回,错误码保持稳定;i18n 组织方式与 04.4.9.2 校验错误一致。

04.4.9.3-029 #[Object] 能否派生泛型结构体,派生宏对类型有哪些限制?

一句话结论

派生宏主要为具体结构体生成 schema 元数据;泛型类型在 GraphQL 类型系统里缺少确定的字段形态,通常要为具体类型落地,或通过显式实现输出类型 trait。

概念解释

GraphQL schema 是静态类型表:每个对象类型有确定的字段名与类型。Rust 泛型结构体带类型参数,编译期无法确定对外类型形状,因此 derive 宏对泛型支持有限。实践做法:定义具体 DTO 结构体承载对外形状,领域层保留泛型;需要复用字段时在具体类型上组合或委托。

原理流程

  1. 识别需要对外暴露的类型,优先落成具体结构体。
  2. 泛型领域模型在服务层组装为具体输出 DTO。
  3. DTO 挂 #[Object] 生成 schema 元数据。
  4. 若确需通用行为,手动实现输出类型 trait 并固定类型映射。
  5. 编译期核对类型约束,缺失 trait 时定位到具体字段类型。

代码或图示

// 不建议:泛型结构体直接挂 Object
// struct Page<T> { items: Vec<T> }
// 建议:为对外响应定义具体类型
struct UserPage { items: Vec<User>, total: u64 }
#[Object]
impl UserPage {
    async fn items(&self) -> &[User] { &self.items }
    async fn total(&self) -> u64 { self.total }
}

常见误区

  • 试图用泛型 DTO 一次映射所有列表响应:GraphQL 类型名与字段类型都需要确定形状。
  • 在泛型参数上套 derive 后遇到陌生 trait 报错:先把类型具体化再排查。

追问

  • 包装类型(newtype)能派生吗?答:普通 newtype 结构体可以按字段暴露;其内部类型需满足对应输出类型约束。
  • 联合体/多态返回怎么建模?答:用 GraphQL 联合类型或接口;Rust 侧枚举与 trait 映射方式以库文档为准。

04.4.9.3-030 如何做字段级权限控制,权限判断放在 resolver 还是统一守卫层?

一句话结论

字段级权限可在统一守卫层按角色/字段表拦截,资源归属判断留在 resolver;两层结合:入口粗粒度控可见性,resolver 细粒度控归属。

概念解释

有些字段仅特定角色可见(如敏感联系方式、内部统计),有些操作需校验资源归属。统一守卫层读取上下文身份与字段元数据,批量判断角色是否允许访问;resolver 内再校验「当前用户是否拥有该订单」。只在 resolver 内判断容易漏挂,统一规则更便于审计。

原理流程

  1. 中间件解析身份写入上下文。
  2. 守卫层按字段与角色表判断是否允许解析。
  3. 未授权字段直接跳过或返回错误,不进入 resolver。
  4. 已授权 resolver 内校验资源归属。
  5. 越权访问记录审计日志。

代码或图示

// 伪代码:守卫按角色过滤字段
async fn guard(ctx: &Context<'_>, field: &str) -> Result<()> {
    let user = ctx.data::<CurrentUser>()?;
    if field == "salary" && user.role != "admin" {
        return Err(FieldError::new("forbidden").with_extension("code", "FORBIDDEN"));
    }
    Ok(())
}

常见误区

  • 只隐藏字段不报错:客户端无法区分「无权限」与「数据为空」,需按约定返回错误或 null。
  • 子对象 resolver 不重复校验归属:直接查询子对象时可能绕过父级判断。

追问

  • 权限规则存哪?答:角色与字段映射可配置化,避免硬编码散落各 resolver;规则变更走配置评审。
  • 字段级性能影响如何?答:守卫在字段调度前执行一次判断,成本低;重逻辑放缓存或预计算。

04.4.9.3-031 错误日志与响应脱敏如何分工,哪些信息绝不能出现在 GraphQL 响应里?

一句话结论

响应只带稳定错误码、可读消息与定位标识;内部堆栈、SQL、连接串、隐私字段进入服务端日志,响应与日志通过请求 ID 关联。

概念解释

GraphQL 响应会下发给客户端,任何内部实现细节都可能被利用。日志侧需要完整上下文定位问题,响应侧需要最小信息。约定:领域错误消息面向用户,技术异常记录日志后包装成通用错误;隐私字段(手机号、身份证)不参与错误拼接。请求 ID 同时出现在日志与响应扩展中,便于用户反馈后追溯。

原理流程

  1. resolver 捕获底层异常,先写入结构化日志(含请求 ID、字段路径、内部原因)。
  2. 转换为对外 FieldError:稳定码、通用消息、请求 ID。
  3. 错误扩展只放非敏感定位信息。
  4. 中间件/扩展层兜底拦截未包装异常。
  5. 定期审计响应样例,检查是否泄漏内部细节。

代码或图示

日志:user_id, request_id, field, sql, stack_trace(仅服务端)
响应:errors[].{ code, message, extensions: { request_id } }

常见误区

  • 把 Debug 格式的底层错误直接转消息:结构体字段、SQL 片段被带出。
  • 响应里返回完整堆栈:帮助攻击者理解技术栈与表结构。

追问

  • 隐私字段如何避免被日志误记?答:日志字段白名单或脱敏序列化,敏感值在记录前掩码处理。
  • 未捕获 panic 会怎样?答:应由框架层兜底转成通用错误并记录,不能让进程崩溃或把 panic 信息下发。

04.4.9.3-032 同一选择集内字段的解析顺序与失败隔离是怎样的?

一句话结论

无依赖字段并发调度,失败字段在响应对应位置为 null 并进入 errors 数组;其他独立字段不受影响,存在依赖的子字段随父失败而跳过。

概念解释

GraphQL 的部分成功模型区别于 REST 的「整请求成功或失败」:一个字段报错不会拖垮整棵查询树。执行器按依赖关系调度:父对象失败,其嵌套子字段不再解析;兄弟字段继续。前端需要按 data 中 null 与 errors 路径逐字段处理,不能假定整请求成功。

原理流程

  1. 执行器按层级调度字段。
  2. 某字段返回错误,记录路径与错误,结果位置置 null。
  3. 其子字段因父失败跳过。
  4. 无依赖的兄弟字段继续执行并返回数据。
  5. 组装响应:data 与 errors 并列下发。

代码或图示

{
  "data": { "user": { "name": "Ann", "orders": null } },
  "errors": [{ "message": "load orders failed", "path": ["user", "orders"] }]
}

常见误区

  • 前端只看 HTTP 200 就认为成功:必须检查 errors 与对应 null 字段。
  • 一个字段失败后期望回滚其他已读数据:只读查询无事务概念,写操作才在 resolver 内管事务。

追问

  • 部分失败时缓存如何更新?答:前端按字段路径局部更新;服务端缓存只缓存成功结果,失败不回填。
  • 错误路径如何定位字段?答:错误携带 path 数组(类型/字段层级),与 data 位置对应。

04.4.9.3-033 引入 async-graphql 时常用 feature 开关有哪些,如何避免不必要编译面?

一句话结论

主库通过 feature 提供对常用类型(时间、UUID、数值等)的集成与 dataloader 等能力;按实际使用开启对应 feature,避免拉入未用依赖拖长编译时间。

概念解释

Rust 库通常用 feature 拆分可选集成:内置标量实现、常用类型映射、dataloader 工具等分属不同开关。Cargo.toml 只声明用到的 feature,未用类型的集成不参与编译。核对 feature 清单应以 docs.rs 主库当前版本为准,历史版本开关名可能调整。

原理流程

  1. 列出 DTO 中实际使用的类型(UUID、时间、Decimal 等)。
  2. 对照文档开启对应 feature。
  3. 需要批量取数时开启 dataloader 相关能力。
  4. cargo check 确认类型解析正常。
  5. 定期清理未使用 feature 以缩短编译。

代码或图示

[dependencies]
# 待确认:feature 名与可用清单以 docs.rs/async-graphql 当前版本为准
async-graphql = { version = "*", features = ["dataloader", "uuid", "chrono"] }

常见误区

  • 照搬老项目的全套 feature:拉入未用类型集成,编译体积增大。
  • 凭记忆写 feature 名:开关名在版本间可能调整,必须核对文档。

追问

  • 如何查看当前启用了哪些 feature?答:cargo tree -e features 可查看依赖与 feature 展开情况。
  • feature 缺失时编译报什么?答:通常是缺少某类型的输出/输入类型 trait 实现,补齐对应 feature 或手写映射。

04.4.9.3-034 juniper 在 Rust GraphQL 生态中的定位是什么,与 async-graphql 的整体架构差异在哪?

一句话结论

juniper 是较早的 Rust GraphQL 服务端库,采用执行器(executor)与根节点注册模型;async-graphql 偏 derive 宏驱动、与异步 Web 框架集成更紧密,两者在元数据生成方式与异步支持上取舍不同。

概念解释

juniper 历史悠久,类型通过 schema 构建期的注册描述或宏声明,执行由 executor 按查询树调度。async-graphql 以派生宏从 Rust 类型直接生成 schema,async resolver 与 Web 集成包配套。选型看团队对宏风格的接受度、异步生态配套与长期维护活跃度;具体 API 形态以各自 docs.rs 当前版本为准。

原理流程

  1. 评估项目对异步 resolver、框架集成与宏便利性的需求。
  2. 对比两库的类型声明方式、错误模型与订阅支持。
  3. 验证关键场景(批量取数、鉴权、订阅)在目标版本可用。
  4. 小规模原型跑通后再决定主选库。
  5. 隔离 GraphQL 层与业务服务层,降低更换成本。

代码或图示

async-graphql:derive 宏 → 类型元数据 → Schema → axum/其他框架集成包
juniper:      schema 注册/宏描述 → RootNode → Executor 调度执行

常见误区

  • 只看 star 数选型:要结合异步配套、订阅支持与团队现有栈。
  • 把两库概念一一对应:错误模型、输入输出类型声明方式并不完全相同。

追问

  • juniper 支持订阅吗?答:订阅与传输支持程度随版本变化,需以其 docs.rs 当前版本与仓库状态为准,必要时标注待确认。
  • 业务层是否要绑定具体库?答:建议领域服务保持库无关,GraphQL 层做适配,便于将来替换。

04.4.9.3-035 juniper 的 RootNode 与 executor 模型如何组织查询执行?

一句话结论

juniper 把查询与变更根组织为 RootNode,执行时由 executor 遍历查询选择集,调用对应字段解析函数并组装结果;上下文贯穿一次执行。

概念解释

在 juniper 模型里,根类型持有各字段的解析函数,RootNode 组合 query 与 mutation 根。执行器接收查询与上下文,按选择集调度字段,返回响应对象。这种模型更接近「注册表 + 调度器」,字段函数签名与上下文获取方式与 async-graphql 不同。具体类型与方法名以 juniper 文档为准。

原理流程

  1. 定义 query 根与 mutation 根的字段解析函数。
  2. 构建 RootNode 组合两根。
  3. 请求进入后创建执行上下文(身份、资源句柄)。
  4. executor 按选择集调用字段函数,并发/顺序策略由库实现决定。
  5. 结果组装为响应值返回。

代码或图示

// 待确认:juniper 当前版本的 RootNode/Context 具体签名以 docs.rs/juniper 为准
// 典型结构:RootNode::new(query_root, mutation_root, subscription_root)
// 字段函数接收 executor 与参数,返回 FieldResult

常见误区

  • 照搬 async-graphql 的 derive 写法到 juniper:类型声明模型不同,需按 juniper 约定组织。
  • 忽略上下文生命周期:上下文通常在一次执行内共享,跨请求资源要另行注入。

追问

  • 两库的错误类型能否互换理解?答:概念上都是字段错误,但类型、扩展信息与转换方式不同;迁移时错误层要重写适配。
  • 如何确认 juniper 对当前 async 运行时的支持?答:查其文档与示例的 tokio/async-std 配套情况,标注待确认项在原型中验证。

04.4.9.3-036 项目在 async-graphql 与 juniper 之间如何做取舍?

一句话结论

优先按「异步框架集成成熟度、派生宏开发效率、订阅与批量取数配套、维护活跃度」综合判断;Rust 后端 Web 服务通常倾向 async-graphql,历史代码或特定抽象偏好可评估 juniper。

概念解释

选型不是单一指标:开发效率(宏生成样板)、运行时配套(WebSocket 订阅、连接池注入)、生态资料与团队熟悉度都要权衡。企业项目还需看版本节奏、issue 响应与安全修复。建议把 GraphQL 适配层做薄,业务服务不直接依赖库类型,保留切换余地。

原理流程

  1. 列出硬需求:异步 resolver、订阅、批量加载、鉴权集成、类型生成。
  2. 两库各跑一个最小原型,验证硬需求。
  3. 评估开发样板量、编译表现与文档完备度。
  4. 检查维护活跃度与已知限制。
  5. 选定后隔离适配层,业务逻辑库无关。

代码或图示

评估清单:框架集成 / 派生便利性 / 订阅支持 / dataloader / 错误模型 / 文档 / 维护状态

常见误区

  • 因为某个库「更老」就更稳定:要看近期发布、安全修复与 issue 处理。
  • 在业务模型里直接使用库的输出/输入类型:迁移时耦合面过大。

追问

  • 两库可以在同一项目共存吗?答:技术上可分服务隔离,但不建议同一 API 层混用;维护两套 schema 成本高。
  • 选型结论需要标注哪些待确认项?答:订阅传输、feature 清单、当前版本 API 以 docs.rs 核实后再固化结论。

04.4.9.3-037 Rust 的 GraphQL 生态相比 Node/Java 成熟度如何评估?

一句话结论

Rust GraphQL 可支撑内部工具与中等规模对外 API,但生态规模、工具链与历史案例不及 Node/Java;选型时要接受部分边缘能力需自行补齐或标注待确认。

概念解释

GraphQL 生态在 JavaScript 侧工具链最完整(代码生成、缓存客户端、调试工具),JVM 侧有成熟服务端实现。Rust 侧主库可用,但高级特性(复杂订阅传输、联邦网关、部分客户端缓存方案)配套较少。评估时区分「服务端查询执行」与「全链路生态」:前者 Rust 已覆盖,后者仍需自建或借用其他语言侧工具。

原理流程

  1. 拆解需求:服务端 schema、resolver、订阅、批量、鉴权、客户端生成。
  2. 逐项核对 Rust 库与周边工具支持度。
  3. 缺口项评估自建成本与风险。
  4. 必要时在网关/BFF 层用更成熟语言承担 GraphQL 聚合。
  5. 原型验证关键链路后再投入。

代码或图示

服务端执行:Rust 可用
订阅传输:需核实当前版本配套
代码生成:依赖 SDL + 前端侧工具
联邦/网关:Rust 配套有限,通常外置

常见误区

  • 假设所有 GraphQL 标准特性在 Rust 库都开箱可用:边缘特性需原型验证。
  • 用生态成熟度单一指标否定或肯定方案。

追问

  • 哪些场景 Rust GraphQL 最稳?答:内部管理接口、BFF 聚合只读查询、配合现成 Web 框架的服务端;复杂实时订阅需额外验证。
  • 标准符合性如何核对?答:查库的测试套件兼容情况与文档说明,不确定行为在原型中实测。

04.4.9.3-038 什么场景应放弃 GraphQL 回到 REST,而不是为用而用?

一句话结论

接口资源模型稳定、缓存与 HTTP 语义重要、团队小或客户端形态单一,REST 更直接;只有存在多端按需取数、聚合多资源、字段频繁裁剪等诉求时,GraphQL 的复杂度才值得引入。

概念解释

GraphQL 带来单一端点、按需取数与类型契约,同时引入查询成本管控、批量加载、订阅运维与前端缓存等新问题。REST 借助 HTTP 缓存、状态码与成熟工具链,在资源清晰的 CRUD 场景更简单。选型要对比两端维护成本:简单接口硬上 GraphQL 会过度设计。

原理流程

  1. 盘点客户端类型与取数差异:多端字段需求是否分化严重。
  2. 评估缓存诉求:是否依赖 HTTP 缓存与 CDN 加速。
  3. 估算服务端防护成本:复杂度、限流、批量加载配套。
  4. 对比团队熟悉度与可观测性配套。
  5. 按场景分域选择:部分服务 REST,聚合层 GraphQL。

代码或图示

REST 优势:HTTP 缓存、状态码语义、工具链成熟、调试直观
GraphQL 优势:按需裁剪、聚合多资源、强类型契约、减少往返

常见误区

  • 把所有内部 CRUD 都包成 GraphQL:牺牲 REST 缓存与简单性。
  • 只看到减少前端往返,忽略服务端查询治理成本。

追问

  • 能否 REST 与 GraphQL 并存?答:可以,按业务域划分;网关层统一鉴权与限流,避免两套契约互不兼容。
  • 开放平台接口更适合哪种?答:资源稳定、公开文档与缓存优先选 REST;按客户端视图聚合的内部 BFF 可考虑 GraphQL。

04.4.9.3-039 GraphQL 与 REST 在契约稳定性上各有什么特点?

一句话结论

REST 契约体现在 URL、方法与响应结构,版本演进常靠显式版本号;GraphQL 契约是 schema 类型与字段,演进主要靠「只增不删」的兼容规则,破坏性变更需客户端协商。

概念解释

两者都需要契约管理,但破坏方式不同:REST 改字段类型、删字段容易让旧客户端解析失败;GraphQL 客户端按选择集取字段,服务端新增字段默认不影响旧查询,但删字段、改类型、加必填参数会破坏现有客户端。GraphQL schema 内省与 SDL diff 便于自动检查兼容性。

原理流程

  1. 梳理现有客户端使用的查询/接口。
  2. 变更前对照兼容性矩阵:新增/可选/删除/改名/改类型。
  3. GraphQL 侧导出 SDL 做 diff 检查;REST 侧核对请求响应结构。
  4. 破坏性变更走版本分支或双写过渡。
  5. 灰度观察旧客户端流量后再下线旧契约。

代码或图示

兼容安全(GraphQL):新增可选字段、新增枚举值(客户端需容错)
高风险:删除字段、字段改名、类型收窄、参数改为必填、枚举删值

常见误区

  • 以为 GraphQL 天然向前兼容:删除/改名/类型变更同样破坏旧客户端。
  • 契约变更只看服务端编译通过:客户端编译与运行时解析才是兼容验证终点。

追问

  • 如何自动检查 schema 破坏性变更?答:用 GraphQL 校验工具对比新旧 SDL,标记删除/类型收窄等变化;CI 中拦截未评审的破坏性变更。
  • REST 契约如何做类似检查?答:契约测试对比请求响应结构,OpenAPI diff 辅助识别字段与类型变化。

04.4.9.3-040 移动端多版本场景下,GraphQL 的字段裁剪能力解决什么问题,边界在哪?

一句话结论

客户端按界面需要选择字段,避免一次拉全量字段;但旧版本 App 持有的是旧查询,服务端不能靠「字段裁剪」解决客户端不升级的兼容问题,仍需服务端向后兼容。

概念解释

多端(App、小程序、Web)字段诉求不同,REST 常为不同端做多个聚合接口;GraphQL 让客户端声明所需字段,服务端按选择集返回。字段裁剪减少冗余传输与多接口维护,但它不替代版本兼容:已安装的旧 App 会持续发送旧查询,服务端必须保留旧字段与旧语义,直到旧版本流量退出。

原理流程

  1. 各端客户端按界面生成 GraphQL 查询(选择集)。
  2. 服务端按选择集解析字段,未选字段不返回。
  3. 服务端演进时保留旧字段语义,旧查询继续可用。
  4. 新字段对旧客户端不可见,旧客户端不感知。
  5. 按版本流量统计,旧版本退出后再下线旧契约。

代码或图示

旧 App 查询:user { id name }
新 App 查询:user { id name avatar level }
服务端:两类选择集都能解析;删除字段前先确认无旧查询引用

常见误区

  • 认为客户端按需取数后服务端可以随意删字段:旧 App 查询仍在运行。
  • 把字段裁剪当成安全边界:裁剪不代表权限控制,敏感字段仍需守卫。

追问

  • 旧版本不升级怎么办?答:服务端保留兼容窗口,配合强制升级提示与版本下线计划;不可强推客户端更新。
  • 选择集过大导致传输膨胀?答:限制单查询复杂度与分页大小,客户端拆分查询或分页加载。

04.4.9.3-041 GraphQL 在网关与 BFF 层分别承担什么角色?

一句话结论

BFF 用 GraphQL 面向特定客户端聚合后端资源、按视图裁剪字段;网关更常做路由、鉴权、限流与协议转换,是否内嵌 GraphQL 取决于架构分层。

概念解释

BFF(Backend For Frontend)按端定制聚合接口,GraphQL 天然适合:把多个下游服务的数据聚合成一次查询返回。网关处于入口位置,主要负责横切治理(认证、限流、审计、协议适配),可转发到 GraphQL 服务,也可自身聚合。Rust 服务可作为 BFF 节点,下游调用内部 REST/gRPC,对外暴露 GraphQL。

原理流程

  1. 客户端请求到达网关,网关完成认证与限流。
  2. 网关按路由转发到 BFF/GraphQL 服务。
  3. BFF 解析查询,调用下游服务(REST/gRPC)聚合数据。
  4. 按选择集组装响应返回。
  5. 下游变更不直接暴露给客户端,由 BFF 做兼容隔离。

代码或图示

客户端 → 网关(认证/限流/路由) → BFF(GraphQL 聚合) → 下游服务(REST/gRPC)

常见误区

  • 把所有业务聚合压进网关:网关变重,发布与故障半径扩大。
  • BFF 直接透传下游字段不做隔离:下游契约变化直接冲击客户端。

追问

  • 多 BFF 之间如何复用逻辑?答:抽公共领域服务与组件库,BFF 只做视图编排,避免复制业务规则。
  • GraphQL BFF 的缓存怎么设计?答:按对象标识缓存只读聚合结果,写操作主动失效;与本地/多级缓存章节衔接。

04.4.9.3-042 N+1 问题在 GraphQL 层与数据访问层分别怎么治理,边界在哪?

一句话结论

GraphQL 层用 dataloader 按批次合并请求,数据访问层提供批量查询能力(IN、批量 mget、批量 join);两层配合,loader 负责合并调度,仓储层负责真正的批量取数。

概念解释

N+1 的根因是「逐条取关联数据」。GraphQL 层问题:resolver 按对象逐个触发查询,dataloader 收集键合并批次。数据访问层问题:仓储方法是否支持按集合取数;如果只提供 find_by_id,loader 内部仍会退化成 N 次单查。治理要两层都到位:批量接口 + 合并调度。

原理流程

  1. 审查嵌套字段 resolver 是否逐个调用单条查询。
  2. 仓储层补充批量方法(按 id 集合查询、批量缓存读取)。
  3. loader 批处理函数调用批量方法,返回键值映射。
  4. dataloader 在执行轮次内合并同键请求。
  5. 压测观察 SQL/缓存命令次数,确认 N+1 消除。

代码或图示

错误:loader 内 for id in keys { repo.find(id).await }  // 仍是 N 次
正确:repo.find_by_ids(keys) 一次 IN 查询,再映射回填

常见误区

  • 只在 GraphQL 层套 dataloader,仓储仍是单条接口:合并没有落地。
  • 批量查询返回全集后在内存过滤:大数据量下内存与传输成本失控。

追问

  • 关联数据来自不同下游服务怎么办?答:loader 内并发调用各下游批量接口,按键合并;跨服务无 join,需在应用层组装。
  • 如何定位残留 N+1?答:开启 SQL/命令日志,观察单请求内重复同模式查询;按字段路径梳理 resolver 取数方式。

04.4.9.3-043 GraphQL 有哪些典型性能与安全风险,如何逐项防护?

一句话结论

主要风险包括深嵌套与广扇出查询、循环引用解析、昂贵字段组合、慢下游叠加与批量放大;防护手段是复杂度/深度限制、字段成本标注、超时与并发控制、批量上限与监控告警。

概念解释

开放字段组合后,攻击者或疏忽客户端可以构造成本极高的查询:多层嵌套列表、重复引用昂贵关联、一次请求拉超大集合。GraphQL 执行把这些字段并发调度到下游,放大数据库与连接池压力。防护要前置(查询评估)与运行时(超时、熔断、限流)结合,不能只靠事后重启。

原理流程

  1. 静态评估:深度、复杂度、扇出大小,超限拒绝。
  2. 字段成本标注:列表与关联查询按参数估算权重。
  3. 运行时超时:单查询与单下游调用分别设超时。
  4. 并发与批量上限:控制同时访问下游的任务数与批大小。
  5. 监控慢查询、错误率与下游耗时,按字段路径定位热点。

代码或图示

防护链路:内省关闭 → 限流 → 复杂度/深度评估 → 超时/并发上限 → 批量查询合并 → 慢查询监控

常见误区

  • 只限制查询文本长度:成本由字段组合决定,字符数不能反映复杂度。
  • 给所有字段相同权重:昂贵关联查询与标量字段成本差异很大。

追问

  • 循环引用类型如何防止无限解析?答:类型建模上避免双向无限嵌套;深度限制兜底,resolver 层不主动递归展开关联。
  • 慢下游拖垮服务怎么隔离?答:下游调用加超时与熔断,BFF 线程池/连接池按下游隔离,避免一个慢服务占满全局资源。

04.4.9.3-044 GraphQL 类型系统对接口演进提供了哪些表达能力,又留下哪些空白?

一句话结论

类型系统用必填/可选、标量/枚举/对象/联合/接口表达数据约束,SDL 可作为契约产物;但它不表达业务规则、权限语义、性能成本与版本策略,这些要在文档、校验层与治理流程中补充。

概念解释

GraphQL 类型能描述字段存在性、类型形状与枚举取值,帮助前后端对齐结构。但「价格必须大于零」「仅管理员可见」「该字段可能为空但需说明」这类约束不在类型内表达。类型是契约的一部分,不是全部契约;业务校验、权限与 SLA 需要配套文档和代码规则。

原理流程

  1. 用类型表达结构:必填 T、可选 Option<T>、枚举固定取值。
  2. 复杂多态用联合/接口建模。
  3. 业务规则放到服务层校验(与 04.4.9.2 衔接)。
  4. 权限与成本在守卫/配置中声明,写入文档。
  5. SDL 与文字说明共同构成对外契约。

代码或图示

type Order {
  status: OrderStatus!   # 类型约束取值集合
  # 类型不表达:金额精度、谁可见、返回耗时
}

常见误区

  • 以为类型生成后契约就完整:错误码、分页约定、限流策略仍需文档。
  • 用可选字段掩盖必填业务约束:该必填的字段放宽为可选会增加校验分支。

追问

  • 联合类型适合什么场景?答:返回多种可区分结果(成功/不同错误类型、多种条目类型),Rust 侧枚举映射。
  • 类型文档写在哪?答:字段描述挂在类型定义上,导出 SDL 时带入;跨字段规则写接口文档。

04.4.9.3-045 什么是对象全局标识(global ID),在缓存与跨类型取数中有什么作用?

一句话结论

全局 ID 把类型名与内部主键编码成不透明标识,便于缓存键归一、跨类型引用与 Relay 风格查询;客户端不暴露内部自增键,服务端按标识反解定位对象。

概念解释

GraphQL 数据图中不同类型可能共享同一 ID 命名空间,纯数字主键可能冲突。全局 ID 通常编码 类型:主键 后 Base64,对外是不透明字符串。缓存键、关系引用与分页游标都可基于它生成。变更失效时按类型加标识精确定位缓存,避免跨类型误删。

原理流程

  1. 对象解析时生成全局 ID:编码类型名与内部主键。
  2. 客户端只持有全局 ID,不接触内部主键。
  3. 查询节点按全局 ID 反解类型与主键,路由到对应 resolver。
  4. 缓存键使用全局 ID 命名空间隔离。
  5. 写操作后按类型加标识失效对应缓存。

代码或图示

内部:User(1001)  → 全局 ID: "VXNlcjoxMDAx"
解码:类型 User + 主键 1001
缓存键:node:VXNlcjoxMDAx

常见误区

  • 全局 ID 直接明文暴露类型与主键:失去不透明意义,也暴露内部编号规律。
  • 不同类型共用解码逻辑却不校验类型前缀:串类型取错对象。

追问

  • 全局 ID 变化后旧客户端持有的标识怎么办?答:标识编码方案要稳定;主键迁移时做映射兼容,不可静默改编码。
  • 与分页游标是什么关系?答:游标可复用全局 ID 编码思路,编码排序键而非单纯主键;具体实现按分页方案定。

04.4.9.3-046 GraphQL 的部分成功错误模型与 REST 状态码模型如何对应,前端该如何处理?

一句话结论

REST 用 HTTP 状态码表达整请求成败,GraphQL 用 data + errors 表达逐字段部分成功;前端必须逐字段检查 null 与错误路径,不能把 200 当成功。

概念解释

REST 语义下,4xx/5xx 通常表示请求未完成,响应体再带错误详情。GraphQL 一次响应内多个字段可能各自成败:整体 HTTP 状态多为 200,错误在 errors 数组,data 对应位置为 null。两套模型映射时,未认证、限流等整请求失败可在 HTTP 层拒绝;字段级业务失败走 GraphQL 错误模型。

原理流程

  1. 整请求级失败(未认证、超限、无法解析查询)由框架返回对应 HTTP 状态。
  2. 进入执行后,字段失败写入 errors 并置 null。
  3. 前端读取响应,遍历 errors 路径,局部更新 UI 状态。
  4. 无错误字段的数据正常渲染。
  5. 错误码用于分支提示,消息用于展示。

代码或图示

REST:404 / 422 / 500 + 错误体,整请求失败
GraphQL:200 + { data: {...}, errors: [{ path, message, extensions }] }

常见误区

  • 前端只判断 response.ok:字段错误被忽略,页面出现空白数据。
  • 后端把字段业务失败也回 500:破坏部分成功模型,其他字段无法返回。

追问

  • 一次 mutation 部分成功怎么处理?答:Mutation 字段串行执行,失败字段返回错误;事务边界在 resolver 内部控制,跨字段回滚需在服务层显式编排。
  • 错误路径与 UI 组件如何对应?答:按路径映射到字段级表单错误,与 REST 表单错误处理思路一致。

04.4.9.3-047 GraphQL 如何处理文件上传,与 REST multipart 上传有什么差异?

一句话结论

GraphQL 文件上传通常借助 multipart 规范把文件与查询变量一起提交,服务端把文件句柄注入 resolver;相比 REST 直接 multipart/form-data,上传走的仍是 GraphQL 变量通道,大小限制与校验由框架层兜底。

概念解释

GraphQL 请求体是 JSON,二进制文件不适合内嵌。生态约定用 multipart 表单同时携带查询字符串、变量映射与文件部分,服务端解析后把上传文件对象作为参数传入 resolver。具体 multipart 规范支持程度以库当前版本为准;文件大小、类型扫描与存储隔离仍需框架与服务层处理。

原理流程

  1. 客户端按上传规范组装 multipart:查询、变量、文件。
  2. 框架层解析表单,校验大小与类型。
  3. 文件句柄注入 GraphQL 参数类型。
  4. resolver 保存文件到存储,返回文件标识。
  5. 校验失败按字段错误或 HTTP 错误返回。

代码或图示

// 待确认:上传参数类型与 multipart 支持以 docs.rs/async-graphql 当前版本为准
// resolver 接收上传对象,读取文件流并落存储

常见误区

  • 在 GraphQL resolver 内同步写大文件:阻塞异步任务,应流式处理并限制大小。
  • 跳过文件类型与病毒扫描:上传入口是常见安全面,不能因走 GraphQL 而省略。

追问

  • 大文件还适合 GraphQL 上传吗?答:超大文件建议走专用上传通道(对象存储直传),GraphQL 只处理元数据与引用。
  • 上传鉴权在哪做?答:框架层先校验身份,文件归属在 resolver 内结合资源权限判断。

04.4.9.3-048 HTTP 头中的凭证与请求元信息如何透传到 GraphQL resolver,链路经过哪些环节?

一句话结论

凭证经 HTTP 头到达框架层,中间件解析后放入请求扩展/上下文,GraphQL 执行器把上下文传给 resolver;resolver 不直接读原始 header,链路为「框架中间件 → 执行上下文 → 字段 resolver」。

概念解释

GraphQL 处理器运行在 Web 框架之上,原始请求头属于框架层对象。中间件在进入 GraphQL 前完成认证解析,把身份与请求元信息(trace ID、语言、设备类型)挂到上下文。执行器构造 Context 时携带这些数据,各 resolver 按类型取出。这样 GraphQL 层不耦合具体 Web 框架的请求类型。

原理流程

  1. 客户端请求携带 Authorization、语言、trace 头等。
  2. 框架中间件解析认证,写入请求扩展。
  3. GraphQL 集成层把扩展数据传入执行上下文。
  4. resolver 通过 ctx.data::<T>() 读取身份与元信息。
  5. 未解析出身份时按未认证错误处理。

代码或图示

HTTP headers → 框架中间件(认证/解析) → 请求扩展 → GraphQL Context → resolver

常见误区

  • resolver 内强行拿原始 Request 读 header:耦合框架类型,测试与迁移困难。
  • 只在根 resolver 读身份,子对象不接上下文:子 resolver 需要身份时同样从 Context 取。

追问

  • trace ID 如何贯穿?答:中间件生成或透传 trace ID 放入上下文,resolver 日志与扩展记录同一 ID。
  • 多租户标识从哪取?答:从认证声明或请求头解析后注入上下文,resolver 按租户隔离数据。

04.4.9.3-049 如何为 GraphQL 接口写测试,查询字符串与 resolver 分别测什么?

一句话结论

单元测试覆盖 resolver 与 loader 业务逻辑,集成测试发送真实查询字符串,断言响应 data 结构与 errors;两者结合验证类型契约与业务行为。

概念解释

GraphQL 测试分三层:resolver/loader 单元测试(注入仓储替身,断言取值与错误);schema 集成测试(构建 schema,执行查询字符串,检查返回形状);契约测试(对照 SDL 校验查询合法)。查询字符串测试能捕获类型不匹配、字段缺失等编译期之外的问题,是 REST 接口测试思路的对应物。

原理流程

  1. 构造测试用 schema,注入替身仓储与 loader。
  2. 执行查询(含变量),得到响应对象。
  3. 断言 data 中目标字段值与结构。
  4. 断言失败场景返回预期错误码与路径。
  5. 导出 SDL 做兼容性 diff,纳入 CI。

代码或图示

// 伪代码:构建 schema 后执行查询字符串
// let res = schema.execute("{ user(id: 1) { name } }").await;
// assert!(res.data.get("user").is_some());

常见误区

  • 只测 resolver 函数不测查询字符串:字段名、参数类型、可选性等 schema 层问题漏网。
  • 测试依赖真实数据库:集成测试应隔离,仓储层用替身或测试库。

追问

  • 订阅怎么测?答:触发事件后断言流收到预期消息,测试流的关闭与错误分支;具体测试辅助以库文档为准。
  • 契约测试如何防破坏性变更?答:保存代表性查询样例,CI 中对新旧 schema 执行,确认旧查询仍合法。

04.4.9.3-050 GraphQL 与 OpenAPI 能否并存,两类契约在一个后端项目里如何分工?

一句话结论

可以并存:对外公开或稳定资源用 OpenAPI/REST 描述,内部聚合 BFF 用 GraphQL schema;两类契约各自生成文档与类型,网关层统一治理,避免同一资源两套互相矛盾的描述。

概念解释

项目演进中常出现历史 REST 接口与新 GraphQL 聚合并存。OpenAPI 描述 REST 端点的路径、方法、请求响应结构;GraphQL SDL 描述数据图类型。同一业务资源在两侧的字段语义要对齐,避免客户端从两个入口拿到不一致的字段定义。契约产物都应入库并随版本评审。

原理流程

  1. 按业务域划分:稳定公开资源走 OpenAPI,客户端聚合视图走 GraphQL。
  2. 两侧 DTO 共享内部领域模型,对外映射各自描述。
  3. 变更时同时检查 OpenAPI 文档与 SDL diff。
  4. 网关统一鉴权、限流与版本策略。
  5. 废弃一侧时按兼容流程下线。

代码或图示

内部领域模型 ←→ REST DTO(OpenAPI 描述)
            ←→ GraphQL 对象(SDL 描述)
两侧字段映射在适配层显式完成

常见误区

  • 同一资源字段在两侧命名/类型不一致:客户端认知混乱,测试与文档冲突。
  • 只维护 GraphQL SDL,OpenAPI 文档过期:旧 REST 调用方失去契约依据。

追问

  • 能否从 GraphQL schema 生成 OpenAPI?答:工具支持有限且语义不完全对应,通常不自动转换;两侧分别维护更可靠。
  • 团队文档如何统一入口?答:对外契约集中归档,标注接口类型、版本与下线计划。

04.4.9.3-051 接口演进中的向后兼容与向前兼容分别指什么?

一句话结论

向后兼容指新服务端能继续服务旧客户端,向前兼容指旧服务端能接受新客户端;演进设计主要保障向后兼容,向前兼容靠客户端宽松解析与服务端忽略未知字段。

概念解释

版本兼容是双向的:服务端升级后,尚未更新的旧客户端仍能正常工作(向后兼容);客户端先发版,旧服务端不理解新字段时不崩(向前兼容)。后端演进以向后兼容为硬目标,因为旧 App 无法强制升级。客户端解析要宽松:忽略未知字段、对未知枚举值容错;服务端反序列化也要避免对未知字段直接报错(与 04.4.9.1 的 deny_unknown_fields 取舍衔接)。

原理流程

  1. 明确兼容方向:服务端新版对旧客户端的承诺。
  2. 变更分类:新增、可选化、删除、改名、改类型。
  3. 旧客户端流量未退出前,旧行为保留。
  4. 客户端解析预留容错:缺字段给默认、未知值走兜底。
  5. 版本退出计划按旧版本安装量与流量制定。

代码或图示

向后兼容:新服务端 ← 旧客户端(主要保障方向)
向前兼容:旧服务端 ← 新客户端(依赖宽松解析与忽略未知)

常见误区

  • 把「编译通过」当作兼容:旧客户端运行时解析才是验证点。
  • 服务端严格拒绝未知字段:新客户端加字段后打旧服务端直接报错。

追问

  • 移动端强制升级能否取消兼容窗口?答:可缩短但不能完全取消,旧版本在升级完成前仍在运行。
  • 兼容测试怎么覆盖?答:保留旧版本请求样例,CI 在新服务端回放,断言响应结构不变。

04.4.9.3-052 为什么新增可选字段通常不破坏兼容,需要注意哪些边界?

一句话结论

新增可选字段(Option/可缺省)不会要求旧客户端发送,旧响应多一个字段也被宽松解析忽略;但新增必填字段、改变默认语义或复用旧字段含义会破坏兼容。

概念解释

旧客户端只认识旧 schema,响应多出的字段按约定被忽略;请求侧旧客户端不传新可选字段,服务端给默认值。安全的新增:可选标量、可选对象、不改变旧字段含义。风险边界:把旧可选字段改成必填、新增必填请求参数、新字段与旧字段语义耦合、枚举新增值(旧客户端可能不认识)。

原理流程

  1. 确认新字段是响应新增还是请求新增。
  2. 请求新增参数设为可选,服务端给默认行为。
  3. 响应新增字段不影响旧客户端解析。
  4. 文档与变更日志记录字段含义与默认值。
  5. 灰度观察后再考虑是否提升必填性。

代码或图示

安全:响应新增 avatar: String?;请求新增 remark: Option<String>
风险:旧字段 age 从可选改必填;新增必填参数 tenantId

常见误区

  • 新增字段直接设必填:旧客户端不传即报错。
  • 复用已废弃字段名改放新含义:旧客户端按旧语义解析出错。

追问

  • 新增枚举值算不算安全新增?答:需客户端容错;旧客户端遇到未知枚举值可能崩溃,属需评估的兼容变更。
  • 响应新增嵌套对象呢?答:可选嵌套对象安全;必填嵌套对象或要求旧客户端解析其内部字段则不安全。

04.4.9.3-053 删除一个对外字段有哪些兼容步骤,不能直接做什么?

一句话结论

删除字段要先标记废弃、保留一个兼容窗口、确认旧客户端无引用后再移除;不能在还有旧版本调用时直接删字段或改其类型。

概念解释

字段删除是破坏性变更:旧客户端查询/解析该字段会失败。标准流程:先在文档与 schema 标注 deprecated,通知调用方迁移;观测流量确认无引用;在兼容窗口后移除字段。REST 与 GraphQL 流程一致,只是废弃标注位置不同。数据库字段可先保留,DTO 层停止对外输出。

原理流程

  1. 确认删除原因与替代字段。
  2. 标记废弃并记录下线日期,文档通知调用方。
  3. 监控该字段的请求/访问日志,确认旧客户端流量退出。
  4. 兼容窗口结束后从响应与 schema 移除。
  5. 数据库字段按内部演进计划另行清理。

代码或图示

标记 deprecated → 通知迁移 → 流量确认无引用 → 兼容窗口 → 移除对外字段 → 清理内部存储

常见误区

  • 先删代码再通知:旧版本请求直接报错,且难以回滚定位。
  • 只看服务端日志不看客户端版本:埋点缺失时误判无引用。

追问

  • 废弃字段还会被 resolver 计算吗?答:应按需短路,废弃字段不再做昂贵查询,避免无效成本。
  • 下线后发现仍有调用怎么办?答:按错误码与版本定位,必要时临时恢复字段,延长兼容窗口。

04.4.9.3-054 字段重命名如何做到平滑过渡,双写双读过渡期怎么安排?

一句话结论

重命名采用「新字段上线、新旧字段并存、旧字段标废弃、流量迁移后下线旧名」的双轨方案;过渡期响应同时输出两个名称,避免任一时刻旧客户端拿不到值。

概念解释

直接改名等于删旧加新,破坏性最强。过渡方案:服务端 DTO 同时序列化新旧两个字段(值相同),客户端逐步切换到新名;旧名标记废弃并保留到兼容窗口结束。请求侧同理:入参同时接受新旧名,内部归一。映射逻辑集中在 DTO 层,领域模型不感知命名过渡。

原理流程

  1. 上线新字段名,响应新旧并存,入参双接受。
  2. 客户端版本逐步改用新名。
  3. 观测旧名引用量下降。
  4. 旧名标记废弃,保留最后一个兼容窗口。
  5. 移除旧名字段与入参兼容逻辑。

代码或图示

过渡期响应:{ "user_name": "Ann", "username": "Ann" }
过渡期入参:同时接受 user_name 与 username,内部映射到同一字段

常见误区

  • 过渡期只输出新名:旧客户端立即失去数据。
  • 新旧字段值在某条路径不一致:双写映射漏分支导致客户端看到矛盾数据。

追问

  • 双写过渡要持续多久?答:取决于旧版本退出节奏,按 App 版本分布与接口流量统计,不拍脑袋定固定周期。
  • GraphQL 场景怎么改名?答:对象上并存两个字段 resolver 指向同一值,旧字段 deprecated 标注,SDL diff 跟踪。

04.4.9.3-055 字段类型变更(如字符串改数字)为什么通常是破坏性变更,有哪些缓解手段?

一句话结论

类型收窄或加宽都会改变客户端解析假设:字符串转数字可能导致旧端解析失败,数字转字符串可能丢失精度;缓解手段是新增独立字段承载新类型,而不是原地改类型。

概念解释

客户端按字段类型写解析逻辑:期望数字收到字符串、或期望字符串收到数字,都可能在解析层崩溃或得到错误值。精度边界(大数、浮点)进一步放大风险。兼容做法:新增字段用新类型,旧字段保留原类型;确需原地迁移时,只能在可强制升级的内部接口并经过全量回归验证。

原理流程

  1. 评估旧客户端对该字段的解析方式与容错能力。
  2. 优先新增字段承载目标类型,旧字段保留。
  3. 双字段过渡期映射值一致。
  4. 旧字段退出后再考虑移除。
  5. 涉及精度(金额、时间戳)单独校验边界。

代码或图示

危险:age: String → age: i32(旧端按字符串解析)
稳妥:新增 age: i32,保留 age_text: String 过渡

常见误区

  • 认为宽松解析能自动转换:多数客户端反序列化严格,类型不符直接报错。
  • 整数改字符串后丢失前导零或大数格式:类型变化伴随格式语义变化。

追问

  • 时间格式从字符串改时间戳算类型变更吗?答:算,格式与解析方式都变;按新增字段或版本分支处理,注意时区与精度。
  • 枚举合并为整数编码呢?答:对外枚举值改名/编码变化属破坏性变更,走双值过渡。

04.4.9.3-056 枚举新增值如何做兼容,旧客户端遇到未知枚举值会怎样?

一句话结论

新增枚举值前要确认客户端能容错处理未知值;不能容错的客户端需要先升级兜底逻辑,服务端新增值后旧端按未知分支处理,避免把新值当成已知值解析。

概念解释

枚举把取值限定在集合内。服务端新增取值(如订单状态 Refunded)时,尚未升级的客户端只认识旧集合,硬编码匹配会落入默认分支或崩溃。兼容策略:客户端解析预留未知兜底;服务端文档说明新值含义;UI 对未知状态展示通用样式。删除或改名枚举值则是明确破坏性变更,不能静默做。

原理流程

  1. 评估各端对未知枚举值的容错实现。
  2. 客户端先发版:未知值走兜底展示,不崩溃。
  3. 服务端再开放新枚举值。
  4. 旧端以兜底样式展示,新端展示完整状态。
  5. 旧端退出后补齐新值的完整 UI。

代码或图示

顺序:客户端容错上线 → 服务端新增枚举值 → 旧端兜底展示 → 旧端退出
反例:服务端先加值,旧端硬编码 match 无兜底分支直接 panic/报错

常见误区

  • 假设客户端遇到未知枚举值会自动忽略:很多语言的反序列化对未知枚举值直接失败。
  • 把内部状态值直接暴露为对外枚举:内部状态调整频繁,对外契约不稳定。

追问

  • 枚举值能向后兼容地删除吗?答:不能,旧端可能仍发送/解析该值;删除走废弃过渡流程。
  • 入参枚举新增值对旧客户端有影响吗?答:旧客户端不会发送新值,风险主要在响应侧;服务端要拒绝旧端不理解的新入参吗?通常不必,按业务规则校验。

04.4.9.3-057 枚举删除值或改名有哪些风险,如何评估引用面?

一句话结论

删除/改名枚举值会让旧客户端发送或解析失败;评估引用面要查日志、埋点与客户端版本分布,确认无旧版本使用后再走废弃下线流程。

概念解释

枚举值是契约的固定字面量。改名在客户端看来就是旧值消失、新值出现;删除同理。风险不仅在响应展示,也在请求入参:旧端提交旧值被服务端拒绝。评估时不能只看当前代码,要覆盖线上旧版本、开放平台第三方调用与后台任务。

原理流程

  1. 梳理枚举值的发送与解析方:Web、App 各版本、第三方、定时任务。
  2. 日志/埋点统计各值出现频率与对应客户端版本。
  3. 确定废弃与下线时间,文档通知。
  4. 过渡期服务端兼容旧值映射到新值。
  5. 确认引用清零后移除旧值。

代码或图示

评估来源:接口日志、客户端埋点、第三方文档、后台任务、消息队列历史消息

常见误区

  • 只搜代码仓库:线上旧版本与历史消息不在仓库内。
  • 消息队列里残留旧枚举值:消费端要兼容历史消息一段时间。

追问

  • 入参旧值服务端还接受吗?答:过渡期可做值映射,旧值归一到新值;下线后严格校验并返回明确错误码。
  • 枚举重排顺序有影响吗?答:若按名称传输无影响;若按数字编码传输,顺序变化即破坏性变更。

04.4.9.3-058 deprecated 标注在 REST 与 GraphQL 中如何落地,下线流程包含哪些节点?

一句话结论

废弃标注对外声明「该字段/接口不再推荐使用」并指明代替项;流程节点为:标注废弃、文档通知、兼容窗口、引用清零、移除实现,每个节点都要有记录可追溯。

概念解释

deprecated 是契约层信号:GraphQL 可在 schema 字段上挂废弃说明,REST 在 OpenAPI 文档与响应头中标记。废弃不等于立即删除,它启动一个可审计的过渡周期。下线决策依赖流量数据与版本分布,而不是日历到期就自动删。废弃字段同时应停止新增使用,并在代码注释中记录背景。

原理流程

  1. 确定替代方案与废弃时间点。
  2. schema/OpenAPI/文档标注废弃与替代项。
  3. 通知所有调用方迁移。
  4. 监控引用量与客户端版本,记录清零时间。
  5. 兼容窗口结束后移除对外字段,内部代码另行清理。

代码或图示

GraphQL:字段上标注 deprecation reason 与替代字段
REST:OpenAPI 标记 deprecated;响应可带 Deprecation 头提示替代接口

常见误区

  • 标注废弃后不再维护文档:调用方不知道替代项与时间点。
  • 废弃字段继续承载新业务需求:过渡逻辑与新需求纠缠。

追问

  • 废弃字段要不要保留文档说明?答:要,写清废弃原因、替代项与下线计划,帮助调用方迁移。
  • 如何审计废弃进度?答:维护废弃清单(字段、标注时间、替代项、流量状态、计划下线日期),定期复盘。

04.4.9.3-059 版本号放在 URI、请求头还是查询参数,三种方案如何取舍?

一句话结论

URI 版本最直观、可缓存路由;Header/媒体类型版本对路径污染小但调试与缓存不直观;查询参数版本弱语义、易被忽略;主流公开 API 多用 URI 版本,内部演进可走无版本兼容策略。

概念解释

版本传递位置是契约设计问题。URI 版本(/v1/users)路由清晰、网关易识别、CDN 可按路径缓存。Header 版本(Accept: application/vnd.api+json; version=2)保持路径干净,但抓包可见性差、客户端易漏传。查询参数版本语义最弱,常被代理与缓存忽略。方案选择要结合网关能力、客户端分布与缓存策略。

原理流程

  1. 评估客户端是否方便改造 URL、是否依赖缓存路径。
  2. 选定版本传递位置并统一全项目。
  3. 网关/框架按版本路由到对应服务或 DTO 分支。
  4. 文档写明版本格式、兼容窗口与下线规则。
  5. 版本间复用公共代码,只隔离变更部分。

代码或图示

URI:        /api/v1/users
Header:     Accept: application/json; version=2
Query:      /users?version=2

常见误区

  • 同一项目混用多种版本位置:客户端与网关理解不一致。
  • 版本号只加在路径,响应结构却不区分:版本分支名存实亡。

追问

  • GraphQL 还需要版本号吗?答:GraphQL 主要靠 schema 兼容演进,破坏性变更才开新端点;版本号使用频率低于 REST。
  • 内部服务间调用怎么版本化?答:优先契约兼容演进,必要时接口内分支,避免服务间 URL 版本爆炸。

04.4.9.3-060 URI 版本化有哪些优点与缺点,什么情况下不适合?

一句话结论

URI 版本直观、可按路径路由与缓存、客户端改造简单;缺点是路径膨胀、版本与代码分支耦合,长期维护多个版本栈;无重大破坏性变更的内部接口更适合靠兼容演进。

概念解释

URI 版本把版本变成路由的一部分,网关按前缀分流,部署与回滚清晰。代价:每个版本一套对外接口形态,代码与文档要并行维护;版本号一旦发布就成为承诺,旧版本不能随意改。当接口变更频繁、客户端形态单一时,维护多版本栈的成本可能超过收益,此时应优先用可选字段与双轨过渡做兼容。

原理流程

  1. 识别是否存在无法兼容的破坏性变更。
  2. 若必须切版本,按 URI 前缀部署新端点。
  3. 旧版本保持稳定,只修缺陷不扩功能。
  4. 客户端迁移后下线旧版本路径。
  5. 公共领域服务在版本层之下复用。

代码或图示

/api/v1/users  → 旧 DTO/旧行为,冻结演进
/api/v2/users  → 新 DTO/新行为
公共领域服务被两版端点复用

常见误区

  • 小改动也开新版本:版本栈无限膨胀。
  • 旧版本偷偷改行为:违反对外兼容承诺,旧客户端出现未预期变化。

追问

  • 版本路径下能混用新旧字段吗?答:一个版本内应保持结构稳定;过渡字段双轨放在同一版本内完成,不另开版本。
  • 如何下线旧 URI?答:先公告与流量迁移,网关层把旧路径临时指向兼容层,确认无流量后移除路由。

04.4.9.3-061 用请求头或媒体类型传递版本有什么优缺点,适合什么场景?

一句话结论

Header/媒体类型版本保持路径干净、版本不污染路由,但客户端易漏传、调试与缓存识别弱;适合内部服务、对路径规范要求高且调用方可控的场景。

概念解释

媒体类型版本把版本写进 Accept/Content-Type,路径只表达资源。优点:资源路径稳定,版本与内容协商绑定;缺点:版本信息藏在头里,网关按路径缓存与限流不便,第三方客户端容易忽略版本头,缺省时还要定义兜底行为。需要在框架层统一解析版本头并校验缺失。

原理流程

  1. 定义版本头格式与缺省版本兜底规则。
  2. 中间件解析头,确定请求版本。
  3. 按版本选择对应 DTO 与行为分支。
  4. 响应头回带实际版本,便于排查。
  5. 文档明确客户端必须发送版本头。

代码或图示

请求:Accept: application/vnd.ann.user+json; version=2
缺省:未携带版本头时按当前稳定版本处理,或拒绝并提示

常见误区

  • 版本头缺失时静默按新版处理:旧客户端拿到未预期结构。
  • 网关按路径做缓存却把版本放在头里:缓存键未含版本,新旧响应串缓存。

追问

  • 媒体类型版本与 URI 版本能混用吗?答:不建议;同一系统选定一种主方案,避免版本识别逻辑分叉。
  • 内部 RPC 服务适合哪种?答:服务间调用可控时,通常优先契约兼容演进;需要并存版本时由框架在消息体或元数据中带版本。

04.4.9.3-062 什么是「无版本号可演进 API」,它依赖哪些前提条件?

一句话结论

不设显式版本号,靠向后兼容规则(只增不删、不改类型、可选新增)长期演进;前提是客户端宽松解析、服务端契约可自动检查、破坏性变更有兜底渠道。

概念解释

很多内部 API 不发 /v2,而是持续在同一接口上做兼容变更:加可选字段、双轨过渡、废弃下线。前提条件:客户端反序列化忽略未知字段、对未知值容错;服务端有契约测试拦截破坏性改动;团队与调用方就兼容规则达成共识。一旦出现无法兼容的变更,仍需临时版本分支或独立端点。

原理流程

  1. 建立兼容规则:新增可选安全,删除/改名/改类型禁止直接做。
  2. CI 做 schema/OpenAPI diff,拦截破坏性变更。
  3. 变更走双轨过渡与废弃清单管理。
  4. 客户端保持宽松解析与向前兼容。
  5. 确有不可调和变更时再开独立版本。

代码或图示

可演进规则:
  安全:新增可选字段、新增可选入参
  禁止:删字段、改名、改类型、参数改必填、枚举删值

常见误区

  • 以为无版本号就可以随意改:兼容约束比显式版本更严格。
  • 客户端严格解析未知字段:服务端一加字段就报错,演进前提不成立。

追问

  • 什么变更无法靠可演进策略消化?答:资源模型重构、字段语义重定义、跨端不兼容的数据结构调整。
  • 如何向新成员推广规则?答:写入接口规范与 CI 门禁,代码评审按兼容矩阵检查。

04.4.9.3-063 PATCH/部分更新接口在版本演进中处于什么位置,如何避免与兼容规则冲突?

一句话结论

PATCH 用可选字段表达「只改传入的字段」,天然适配增量演进;新增可更新字段设为可选,旧客户端不传即不更新,但要区分「字段未传」与「显式置空」两种语义。

概念解释

部分更新接口的参数多为 Option:未传表示不修改,传 Some 表示修改。这与 DTO 演进的可选字段思路一致。难点是语义区分:None(未提供)与 Some(None)(置空)需要两层包装表达。PATCH 接口演进时不能把可选参数直接改成必填,否则旧客户端部分更新失败。

原理流程

  1. 更新 DTO 用可选字段承载增量修改。
  2. 区分未传与置空:必要时用双重 Option 或显式操作类型。
  3. 服务层只合并传入字段,不覆盖未传字段。
  4. 新增可更新字段保持可选,默认行为明确。
  5. 校验规则按字段单独触发,不强制整对象校验。

代码或图示

#[derive(Deserialize)]
struct UpdateProfile {
    name: Option<String>,
    avatar: Option<Option<String>>, // None: 未传;Some(None): 置空
}

常见误区

  • 把未传字段当作空值覆盖:旧客户端更新后清掉了未提交的字段。
  • PATCH 复用创建 DTO:创建必填约束污染部分更新语义(与 04.4.9.2 的 PATCH 讨论衔接)。

追问

  • 部分更新的校验怎么组织?答:只校验实际传入的字段;跨字段规则在更新后整体校验。
  • PATCH 与 PUT 怎么选?答:PUT 表示整体替换,PATCH 表示增量修改;演进频繁的资源优先 PATCH。

04.4.9.3-064 兼容性回归测试怎么做,如何用旧请求样例保护新服务端?

一句话结论

保存各版本代表性请求与响应样例,在新服务端回放旧请求,断言响应结构与旧约定一致;配合 schema/OpenAPI diff 自动识别破坏性变更,纳入 CI 门禁。

概念解释

兼容回归的核心是「旧客户端还在怎么调」。测试资产包括:旧版本请求样例(查询字符串、JSON 体)、期望响应结构、错误样例。服务端变更后自动回放,对比关键字段与类型。静态 diff 负责识别契约结构变化,样例回放负责验证运行时行为,两者互补。

原理流程

  1. 从线上日志与旧版本整理请求样例,脱敏后入库。
  2. 固定期望响应的结构与必填字段(不锁死无关文案)。
  3. CI 构建新服务端,注入测试数据后回放样例。
  4. 对比响应:缺失字段、类型变化、错误码变化即失败。
  5. 破坏性变更需评审通过后才能调整样例基线。

代码或图示

样例库:v1 各接口请求 + 期望响应结构
CI:构建 → 回放旧样例 → 结构对比 → 阻断不兼容改动

常见误区

  • 只跑新客户端视角的测试:旧请求路径未覆盖。
  • 断言锁死完整响应文案:正常文案调整被误判为不兼容。

追问

  • 样例数据脱敏怎么做?答:真实手机号、身份证等替换为固定测试值,保留结构与类型。
  • 无法保存历史请求怎么办?答:至少覆盖公开文档示例与主流程查询;上线后补充回放资产。

04.4.9.3-065 消费者驱动契约测试解决什么问题,在 Rust 后端如何落地?

一句话结论

消费者驱动契约由客户端定义「我需要的字段与行为」,服务端按契约验证;它把兼容验证从集中式样例库转为按消费者关系维护,防止服务端改动悄悄破坏某一方。

概念解释

传统契约测试常由提供方编写,可能漏掉真实消费者诉求。消费者驱动:每个客户端(Web、App、第三方)把依赖的接口字段、类型与用例写成契约,提供方 CI 验证全部契约通过。Rust 后端可在集成测试中按契约样例调用本地服务,断言字段存在与类型;跨语言消费者用其工具生成契约,提供方对照执行。

原理流程

  1. 识别服务的消费者清单与各自使用的字段。
  2. 消费者产出契约:请求样例 + 期望字段/类型/错误。
  3. 提供方 CI 拉取契约,启动测试服务执行验证。
  4. 任一契约失败则阻断发布。
  5. 接口废弃时同步标记对应契约退役。

代码或图示

消费者(Web/App) → 定义契约(字段/样例/错误) → 提供方 CI 验证全部契约

常见误区

  • 契约只测字段存在不测类型:类型变化漏网。
  • 契约与真实查询脱节:客户端改了用法但契约未更新,验证失去意义。

追问

  • 契约放哪里维护?答:随消费者代码或独立契约仓库,提供方只读引用;版本随接口演进。
  • 内部小项目需要完整消费者驱动吗?答:轻量做法是维护核心样例回放;消费者多、外部合作时再引入完整契约体系。

04.4.9.3-066 灰度发布期间如何做双写双读,保证新旧版本与新旧数据一致?

一句话结论

灰度阶段新老服务并存,写侧按策略双写或迁流写入,读侧按版本/灰度标签路由;数据迁移在后台补齐,任何一侧回滚都能读到一致数据。

概念解释

接口版本切换常伴随数据模型变化。双写双读是过渡手段:写请求同时落新旧存储(或以新存储为准、旧存储补齐);读请求按灰度标识走新旧路径。关键是幂等、冲突优先级与回滚路径:双写失败要可重试,读侧不能在新旧数据源间拿到矛盾快照。灰度按用户/租户维度逐步放量。

原理流程

  1. 确定数据迁移方向与新旧存储映射。
  2. 写侧:新写入双写,后台任务回填历史数据。
  3. 读侧:灰度标签路由到新或旧服务/存储。
  4. 校验两侧数据一致性,对账修复差异。
  5. 全量切新后下线旧写路径与旧存储读取。

代码或图示

写:新请求 → 写新库 → 异步双写旧库(失败重试/对账)
读:灰度用户 → 新库;其余 → 旧库
回滚:路由切回旧库,双写停止前旧库数据完整

常见误区

  • 双写非幂等:重试导致重复数据,写入要带幂等键。
  • 回填未完成就切读:新库缺历史记录,查询出现空洞。

追问

  • 双写顺序怎么定?答:以主写存储为准,另一写异步补偿;主写失败即失败,补偿失败进对账队列。
  • 灰度按什么维度切?答:用户段、租户、百分比或白名单;粒度支持快速回滚。

04.4.9.3-067 数据库结构迁移与 DTO 演进如何配合,避免库表变更卡住接口兼容?

一句话结论

库表迁移走「先加列/表、双写迁移、读切换、删旧列」的兼容步骤,DTO 演进与存储演进解耦:接口兼容窗口内 DTO 可映射新旧两种存储结构。

概念解释

接口要向后兼容,不代表数据库不能改。存储变更应分阶段:新增结构先与旧结构并存,应用层适配两种读取;数据迁移完成后再切读,最后清理旧列。DTO 层是隔离层:对外字段稳定,内部按仓储实现映射新旧表。直接删列改类型会破坏尚未迁移的旧读取路径。

原理流程

  1. 设计新表/新列,保持旧结构可用。
  2. 应用层双写,后台回填旧数据到新结构。
  3. 校验一致后读侧切到新结构。
  4. DTO 映射层隔离新旧字段命名与类型。
  5. 确认无旧读取后下线旧列与旧代码路径。

代码或图示

加新列/表 → 双写+回填 → 读切换 → 验证 → 删旧列
DTO 对外字段稳定,仓储层负责新旧存储映射

常见误区

  • 迁移脚本直接重命名旧列:旧版本应用启动即报错。
  • DTO 直接暴露表结构:存储重构冲击对外契约。

追问

  • 迁移期间回滚怎么办?答:新旧结构并存且双写可回切;不可逆变更(删列)放在最后一步。
  • 大表回填怎么控制影响?答:分批限速、错峰执行,避免锁表与线上 IO 高峰;具体工具与锁策略按数据库类型核对。

04.4.9.3-068 客户端 SDK 或类型生成如何与接口版本绑定,避免版本错配?

一句话结论

SDK/类型从受控契约产物(SDL/OpenAPI)生成并标注对应契约版本,客户端锁定 SDK 版本;服务端兼容窗口内保证对应 SDK 版本可用,废弃 SDK 版本随旧接口一起下线。

概念解释

代码生成把契约变成类型与方法。生成产物要记录来源契约版本,避免客户端拿着旧类型调新接口。SDK 发布遵循语义化版本:兼容 bump 新增可选能力,破坏性 bump 升主版本。服务端对外承诺哪些 SDK 版本在兼容期内可用;下线旧接口时同步公告对应 SDK 退役。

原理流程

  1. 契约(SDL/OpenAPI)入库作为生成唯一来源。
  2. 构建脚本生成类型/SDK,附带契约版本元数据。
  3. 客户端依赖锁定 SDK 版本,升级跟随接口变更。
  4. 服务端兼容矩阵列出支持的 SDK/客户端版本。
  5. 旧接口下线前公告对应 SDK 退役计划。

代码或图示

契约产物 → 代码生成 → SDK 包(版本号 + 契约版本) → 客户端锁定依赖
服务端兼容矩阵:旧 SDK 版本 → 支持到日期

常见误区

  • 手写 SDK 与服务端结构脱节:字段漂移无自动检查。
  • 生成产物不锁版本:构建时拉到最新契约,行为随上游变动。

追问

  • 类型生成在 Rust 侧有哪些链路?答:GraphQL 侧多为 SDL 给前端生成 TS 类型;Rust 服务端类型由 derive 直接产生,OpenAPI 可由 utoipa 等生成(与 04.4.9.2 衔接)。
  • SDK 破坏性变更怎么通知?答:发版说明 + 兼容期公告,旧 SDK 关键缺陷修复至退役日。

04.4.9.3-069 契约文档如何保持单一事实源,避免文档与实现漂移?

一句话结论

契约结构从代码或受控产物自动生成(schema derive、OpenAPI 注解),文档只补充语义说明;禁止手工维护第二份结构清单,变更评审对比生成产物 diff。

概念解释

文档漂移是接口维护常见问题:代码改了字段,文档没更新。单一事实源原则:字段名、类型、必填性由代码推导生成;文字文档承载业务含义、错误码、示例与约束。生成产物入库可评审,对外门户从产物发布。评审时同时看代码、生成契约与说明文档三处一致性。

原理流程

  1. 代码注解/derive 作为结构唯一来源。
  2. 构建期导出 SDL/OpenAPI 产物入库。
  3. 文字文档挂接业务规则、示例与错误码。
  4. 评审检查产物 diff 与文档更新是否同步。
  5. 对外文档门户从受控产物发布,不接受手工粘贴副本。

代码或图示

Rust 类型/注解 → 自动生成 SDL/OpenAPI → 入库评审 → 对外发布
人工文档:业务语义、错误码表、请求示例、约束说明

常见误区

  • 文档手抄字段表:两次维护必然漂移。
  • 生成产物不入库:评审无法看到结构变化,线上才暴露。

追问

  • 自动生成覆盖不到的语义怎么补?答:错误码、权限、分页约定等写入规范文档与接口说明,类型上挂描述属性带入产物。
  • 文档谁负责更新?答:接口变更的提交者同步更新说明;评审作为检查项。

04.4.9.3-070 响应新增字段对「严格解析」客户端有什么风险,如何提前识别?

一句话结论

严格解析(拒绝未知字段、未知枚举值即报错)的客户端会被服务端新增字段打断;风险要在客户端适配层识别并改为宽松解析,服务端发布前检查依赖客户端的解析策略。

概念解释

不同客户端反序列化策略不同:宽松实现忽略未知字段,严格实现对未知键/未知值直接失败。服务端按兼容规则新增可选字段后,宽松端无感,严格端可能报错。识别方式:审查各端 DTO 定义与反序列化配置,确认是否开启未知字段拒绝;服务端日志关注解析类错误是否随版本出现。

原理流程

  1. 梳理客户端解析配置:是否拒绝未知字段、未知枚举值。
  2. 严格端先改为宽松容错(未知字段忽略、未知值兜底)。
  3. 服务端新增字段前评估影响面。
  4. 灰度观察解析错误率与客户端版本分布。
  5. 严格端未改造前,相关新增暂缓下发。

代码或图示

风险点:反序列化配置 deny_unknown_fields;枚举无兜底分支;结构体字段强匹配
缓解:忽略未知字段;未知枚举走默认/原始值保留

常见误区

  • 认为「可选新增」对所有客户端安全:安全前提是客户端宽松解析。
  • 只在 Web 端确认,遗漏 App 旧版本与第三方集成。

追问

  • Rust 服务端入参严格解析会影响谁?答:影响调用服务端的客户端请求;服务端自身对未知字段的策略见 04.4.9.1。
  • 发现严格端未改造怎么办?答:延迟新字段下发,或在该端适配后再开放;不要让客户端硬扛解析错误。

04.4.9.3-071 客户端灰度与回滚时,服务端如何安排兼容窗口与兜底行为?

一句话结论

服务端在客户端灰度前就保留旧行为,按版本/标识区分新旧处理;回滚发生时旧服务端与旧数据仍可工作,兼容窗口覆盖灰度、全量与回滚全过程。

概念解释

发布是双向风险:新版客户端可能有问题需要回滚,服务端不能在客户端灰度中途撤掉旧契约。兼容窗口从旧版本停止新增覆盖,到旧版本流量清零后结束。服务端按客户端版本或能力标识路由行为:新版用新字段/新行为,旧版走旧路径。回滚演练要验证旧链路完整可用。

原理流程

  1. 发布前确认旧契约保留,兼容窗口计划成文。
  2. 客户端按比例灰度,服务端识别版本/能力。
  3. 异常时客户端回滚,服务端旧链路继续承接。
  4. 全量稳定后统计旧版本流量退出。
  5. 窗口结束评审下线旧契约。

代码或图示

窗口起点:旧版本停止被强制覆盖
窗口内:新旧行为并存,按版本/能力路由
窗口终点:旧版本流量清零 + 观察期

常见误区

  • 服务端先于客户端全量下线旧字段:回滚后客户端无数据。
  • 兼容窗口只按日历定,不看旧版本实际流量。

追问

  • 能力标识比版本号好在哪?答:按实际支持的能力协商,避免版本号与功能不一致;头或字段中带能力集合。
  • 回滚演练覆盖哪些路径?答:旧请求解析、旧 DTO 映射、旧存储读取与相关错误分支。

04.4.9.3-072 错误码体系如何随接口演进,废弃错误码能不能直接删?

一句话结论

错误码是对外契约:新增码向后兼容,修改语义或删除码会破坏客户端分支判断;错误码沿用稳定字符串/枚举,废弃码进入清单,确认无客户端依赖后再下线。

概念解释

前端按错误码做分支提示与重试,文案可变、码不可乱改。演进规则:新场景加新码,不复用旧码表达新含义;同一错误避免多码并存造成分支混乱。废弃错误码与字段下线流程一致:公告、观测引用、兼容窗口后移除。错误码体系应与 04.4.9.2 校验错误、GraphQL 扩展码统一规划。

原理流程

  1. 定义错误码命名规则与层级(领域 + 场景)。
  2. 新错误场景分配新码,消息面向人读。
  3. 文档维护错误码表与含义。
  4. 废弃码标记并统计客户端引用。
  5. 兼容窗口后从响应中移除废弃码。

代码或图示

新增:USER_NOT_FOUND(安全)
禁止:把 USER_NOT_FOUND 的触发条件改成参数错误
废弃:老码进入清单,确认无分支引用后下线

常见误区

  • 错误码随业务调整改含义:客户端按旧码处理新场景。
  • 同一问题返回不同码:前端分支与测试用例混乱。

追问

  • HTTP 状态码与业务错误码什么关系?答:状态码表达协议层成败,业务码表达场景;两者分层映射,不能互相替代。
  • 错误码要不要国际化?答:码稳定不变,消息按语言翻译;扩展信息保留码与请求 ID。

04.4.9.3-073 分页、排序、过滤参数如何演进,加参数时如何不破坏旧客户端?

一句话结论

新增分页/排序/过滤参数设为可选并给默认行为,旧客户端不传即沿用默认;已有参数改必填、改默认排序或改编码格式属于破坏性变更,需过渡处理。

概念解释

列表接口参数会随业务增加:新过滤条件、新排序字段、游标分页替换页码。兼容规则与字段演进一致:新增可选安全,改默认行为不安全。分页模式从 offset 改游标时,旧客户端按页码调用,过渡期两套参数并存,服务端内部归一。排序字段集合新增要注意客户端传入未知排序字段时的容错。

原理流程

  1. 新参数可选,文档写明默认值与默认排序。
  2. 旧参数保留,新参数独立增加。
  3. 分页模式切换期双模式支持,内部映射统一查询。
  4. 观测旧参数调用量后下线旧模式。
  5. 未知排序/过滤字段拒绝并返回明确错误码。

代码或图示

安全新增:filter=status(可选,不传不过滤)
风险:默认排序从 createdAt 改为 updatedAt;page 模式强制改 cursor

常见误区

  • 新增过滤参数后默认过滤掉旧数据:旧客户端列表结果静默变化。
  • 排序字段开放白名单外输入:SQL 注入或异常排序风险。

追问

  • 分页大小默认值能调整吗?答:调小影响客户端页数预期,调大增加服务成本;变更需公告并观察。
  • 游标格式升级怎么办?答:游标带版本前缀,新旧游标解析兼容;旧游标过渡期有效。

04.4.9.3-074 时间、货币、精度类敏感字段在演进时有哪些特殊约束?

一句话结论

时间必须明确时区与格式,货币必须明确币种与小数精度,数值字段演进要防精度丢失;这类字段改编码方式(字符串/时间戳/分单位)属破坏性变更,需新字段过渡。

概念解释

敏感字段的兼容问题隐藏在格式里:同一时间 RFC3339 与 Unix 时间戳互不兼容;金额「元」与「分」单位混用导致百倍错误;浮点金额精度漂移。演进时格式与单位是契约的一部分,不能静默调整。文档必须写清时区、格式、单位与精度,测试样例覆盖边界值。

原理流程

  1. 字段定义写明格式:时间 RFC3339 带时区,金额含币种与最小单位。
  2. 变更编码方式时新增字段,旧字段保留过渡。
  3. 序列化层统一格式转换(与 04.4.9.1 时间/大数讨论衔接)。
  4. 测试覆盖边界:零值、负数、最大精度、时区转换。
  5. 灰度核对两侧金额与时间一致后再切新字段。

代码或图示

时间:2026-11-19T08:00:00+08:00(明确时区)
金额:{ "currency": "CNY", "amount": "19.90" }(字符串保精度)
禁止:浮点存金额;无单位整数直接当元

常见误区

  • 时间不带时区:客户端按本地时区解析,展示与存储错位。
  • 金额用浮点:二进制精度导致对账差异。
  • 单位从「分」改「元」不公告:数值放大百倍。

追问

  • 时间字段改时间戳要注意什么?答:秒/毫秒精度、时区由 UTC 承载;新旧格式双字段过渡。
  • 大额整数序列化有什么坑?答:JSON 数值精度边界见 04.4.9.1;超出安全整数范围用字符串传输。

04.4.9.3-075 一个大版本从宣布到下线要经历哪些阶段,废弃周期由什么决定?

一句话结论

阶段为:预告与规划、双轨并存、迁移引导、流量观测、兼容窗口、下线移除;周期长短由旧版本流量分布、第三方依赖与回滚风险决定,不设统一固定天数。

概念解释

版本下线不是发个公告就删。每个阶段有准入准出标准:预告明确替代版本与时间;双轨期新旧可用;迁移期引导调用方改造;观测期确认旧流量下降;窗口期保留兜底;最后移除实现。周期受移动端不升级比例、第三方集成节奏、合规留存要求影响,内部接口可短,对外开放与金融类接口要长。

原理流程

  1. 立项:替代方案、影响面、目标下线日期。
  2. 公告:调用方清单、迁移指南、时间节点。
  3. 双轨:新旧版本并存,旧版冻结功能。
  4. 观测:按日志/埋点统计旧版本流量与版本分布。
  5. 窗口结束评审,移除旧路由、旧 DTO 与旧代码。

代码或图示

预告 → 双轨并存 → 迁移引导 → 流量观测 → 兜底窗口 → 移除实现
准出依据:旧版本流量清零 + 观察期无异常 + 第三方确认

常见误区

  • 周期到期就删,不核对实际流量:长尾旧版本仍在调用。
  • 旧版本继续修新需求:过渡代码永久化。

追问

  • 第三方调用怎么纳入观测?答:开放平台日志按应用标识统计,下线前逐个确认通知回执。
  • 下线后残留旧请求怎么处理?答:网关返回明确版本退役错误码与文档链接,记录来源,必要时临时恢复。

04.4.9.3-076 GraphQL schema 弃用与 REST 版本化在兼容策略上有什么本质差异?

一句话结论

REST 常靠显式版本号并存多套接口形态;GraphQL 靠 schema 内字段废弃与「只增不删」演进,破坏性变更才开新端点;两者最终都要走兼容窗口与流量观测。

概念解释

GraphQL 单端点下,版本体现为 schema 字段的新增/废弃,客户端按选择集适配;REST 资源路径与响应结构固化,大变更倾向新开版本路径。差异源于接口形态:GraphQL 客户端自选字段,服务端可长期保留废弃字段;REST 多版本并存维护成本随版本数增长。相同点:删除与改类型都是破坏性变更,都需要通知、观测与下线流程。

原理流程

  1. REST:评估变更是否能在旧响应结构内兼容;不能则新版本路径。
  2. GraphQL:评估字段能否废弃过渡;schema diff 检查兼容性。
  3. 两侧都维护废弃清单与流量观测。
  4. 客户端迁移完成后移除旧契约。
  5. 网关统一版本退役与错误提示。

代码或图示

REST:/v1/users 与 /v2/users 并存,结构各自冻结
GraphQL:User 类型上旧字段 deprecated,新字段并存,选择集逐步切换

常见误区

  • 以为 GraphQL 不需要版本管理:破坏性 schema 变更同样需要端点级方案。
  • 以为 REST 不能做字段级废弃:REST 也可在同一响应内双轨字段过渡。

追问

  • GraphQL 大版本怎么对外发布?答:schema 长期兼容演进;无法兼容时独立 GraphQL 端点或 BFF 隔离,SDL 分别管理。
  • 两种模式下客户端缓存怎么配合?答:字段废弃后客户端停止查询;REST 版本切换后缓存键按版本隔离。

04.4.9.3-077 多端旧版本长期不升级时,服务端兼容策略怎么分层处理?

一句话结论

按版本流量分层:活跃旧版本保留兼容路径,长尾版本引导升级或走退役流程;服务端识别版本能力,旧版走旧 DTO,新版走新字段,避免为长尾长期背负全部旧逻辑。

概念解释

App 旧版本分布呈长尾:部分用户长期不更新。兼容策略要按数据分层:高占比旧版本必须承接,极低占比且风险可控的版本引导强制升级或退役。服务端按版本号/能力标识路由 DTO 分支,领域服务复用。监控旧版本占比趋势,定期评估兼容成本与下线收益。

原理流程

  1. 统计各端版本分布、接口流量与崩溃率。
  2. 划分层级:主力版本、承接版本、长尾退役版本。
  3. 服务端按版本/能力选择 DTO 与行为分支。
  4. 长尾版本弹升级提示或限制部分能力。
  5. 占比低于阈值并经评审后退役旧契约。

代码或图示

分层依据:版本安装占比、接口流量、错误率、业务重要性
路由:版本标识 → 旧 DTO 分支 / 新 DTO 分支(共用领域服务)

常见误区

  • 为全部历史版本保留代码:兼容分支累积成维护负担。
  • 不看数据一刀切退役:占比高的旧版本被阻断,影响业务。

追问

  • 强制升级怎么落地?答:服务端返回最低支持版本,客户端对比后阻断或引导;强制策略需评审风险。
  • 旧版本依赖的旧后端服务何时停?答:随旧版本流量退出节奏安排,提前公告。

04.4.9.3-078 如何用一张兼容性检查矩阵评审接口变更,新增、修改、删除分别怎么判?

一句话结论

矩阵按「字段/参数/枚举/错误码/分页维度」交叉判断操作类型:新增可选为安全,类型/语义/必填性修改为高风险,删除/改名需过渡;评审逐项打标记并记录结论。

概念解释

兼容评审容易凭感觉,矩阵把判断标准化。行是契约元素(响应字段、请求参数、枚举值、错误码、分页排序),列是操作(新增、可选改必填、改名、改类型、删除),交叉格标注安全/过渡/禁止。评审时变更逐项过矩阵,高风险项必须有过渡方案与兼容窗口。

原理流程

  1. 列出本次变更涉及的全部契约元素。
  2. 逐项对照矩阵判断操作风险等级。
  3. 安全项直接通过;过渡项排双轨计划;禁止项改方案。
  4. 记录评审结论、替代方案与下线日期。
  5. CI diff 与评审记录互相印证。

代码或图示

元素        新增可选  改必填  改名  改类型  删除
响应字段    安全      高风险 过渡  高风险  过渡
请求参数    安全      高风险 过渡  高风险  过渡
枚举值      需容错    —      过渡  —      过渡
错误码      安全      禁改语义 过渡 —    过渡

常见误区

  • 只评审响应字段,遗漏请求参数与枚举值。
  • 高风险项批准直接上线,无双轨与观测计划。

追问

  • 矩阵结论放哪?答:接口评审记录与废弃清单关联,变更 PR 中附矩阵填写结果。
  • 工具能否自动出矩阵?答:schema/OpenAPI diff 可初判结构变化,语义与必填风险仍需人工评审。

04.4.9.3-079 DTO 与领域模型为什么要解耦,在版本演进中起到什么隔离作用?

一句话结论

DTO 是对外契约形态,领域模型是内部业务形态;两者分层映射后,内部重构不冲击对外兼容,对外版本过渡也不污染领域逻辑。

概念解释

如果领域结构体直接序列化对外,内部字段调整就变成接口变更。DTO 层承担双向映射:入参 DTO 转领域模型,领域模型转出参 DTO。版本演进时,同一领域模型可映射多个版本 DTO;废弃字段只存在于旧 DTO。映射集中在适配层,便于测试与审查。

原理流程

  1. 定义请求/响应 DTO,结构服从对外契约。
  2. 服务层接收领域模型,不依赖 DTO 类型。
  3. 入参映射:DTO 校验后转换为领域命令。
  4. 出参映射:领域模型按版本组装对应 DTO。
  5. 内部重构只改领域层与映射,对外字段保持稳定。

代码或图示

请求 DTO → 校验/映射 → 领域命令 → 领域模型 → 映射 → 响应 DTO(按版本)
旧版本 DTO 与新版本 DTO 并存,映射到同一领域模型

常见误区

  • 领域模型 derive 序列化直接对外:内部重命名/改类型立即破坏契约。
  • 映射逻辑散落在 resolver/handler:重复且难审查,应集中在 DTO 转换层。

追问

  • 映射层要不要测?答:要,覆盖字段缺失、类型转换与边界值;映射错误是接口缺陷常见来源。
  • DTO 能不能复用校验库规则?答:可以,校验挂在 DTO 层(与 04.4.9.2 衔接),领域层做业务规则校验。

04.4.9.3-080 复盘一个典型的向后兼容破坏案例,问题出在哪一环?

一句话结论

典型案例是「内部字段改名/类型调整后直接对外发布,旧客户端解析失败」;问题通常出在缺少契约 diff、DTO 未隔离、上线前无旧样例回放。

概念解释

复盘框架:变更内容、受影响客户端、故障表现、发现环节、根因、补救措施。常见链路:开发者重构领域字段 → DTO 未隔离跟随改名 → 评审未对照兼容矩阵 → CI 无旧样例回放 → 旧 App 解析报错。补救分三层:紧急回滚或热修复恢复旧字段;通知受影响版本;补契约测试与评审门禁防止复发。

原理流程

  1. 还原变更前契约与变更后差异。
  2. 定位破坏点:字段删除/改名/类型收窄/必填化。
  3. 梳理受影响客户端版本与故障面。
  4. 紧急恢复旧契约,双轨过渡。
  5. 补 CI 回放、兼容矩阵评审与 DTO 隔离规范。

代码或图示

案例链:内部重构 → DTO 跟随变更 → 评审缺矩阵 → 无旧样例回放 → 旧端解析失败
补救:回滚/补字段 → 通知客户端 → 补测试门禁 → 规范 DTO 分层

常见误区

  • 复盘只归责个人:应补流程与工具门禁。
  • 只修线上字段,不补回归测试:同类问题再次发生。

追问

  • 如何快速判断线上报错是兼容破坏?答:按错误路径对照旧样例,检查响应是否缺字段/类型变化;结合客户端版本与发布时间定位。
  • 对外接口变更评审 checklist 包含什么?答:兼容矩阵、旧样例回放、废弃清单更新、文档与 SDK 版本、灰度回滚方案。

04.4.9.3-081 版本演进中 feature flag(功能开关)如何配合接口变更使用?

一句话结论

开关把新字段/新行为与发布解耦:代码先上线但默认关闭,灰度按开关放量;出问题回退开关而不必回滚发布,契约过渡期间新旧行为并存。

概念解释

feature flag 控制功能可见性与行为分支,配合接口演进:新 DTO 字段可先在代码中就绪,开关打开后才对对应流量返回;旧行为分支保留到开关退役。开关分灰度开关与永久业务配置两类,接口过渡用的灰度开关要有明确下线计划,避免开关长期堆积。

原理流程

  1. 变更代码随发布上线,开关默认关闭。
  2. 按白名单/比例/租户打开新行为。
  3. 观测指标,异常则关开关回退行为。
  4. 全量稳定后移除旧分支与开关。
  5. 开关清单记录用途、持有人与退役日期。

代码或图示

代码就绪(关) → 灰度打开 → 观测 → 全量 → 删旧分支/拆开关
开关维度:用户段、租户、客户端版本

常见误区

  • 开关永不拆除:行为分支叠加,代码复杂度失控。
  • 开关控制安全校验:鉴权类逻辑不应依赖可随意关闭的开关。

追问

  • 开关配置存哪?答:配置中心或环境配置,动态下发;灰度开关与业务配置分开管理。
  • 开关与双写双读怎么配合?答:开关控制读侧路由,写侧双写按迁移阶段独立编排。

04.4.9.3-082 接口变更的文档与 changelog 如何管理,调用方如何获知breaking change?

一句话结论

维护按版本/日期的变更日志:新增、变更、废弃、移除分类记录,破坏性变更显著标注替代方案与时间点;文档门户、SDK 发版说明与公告渠道同步触达调用方。

概念解释

变更日志是兼容流程的对外承诺记录。条目包含:日期、接口/字段、变更类型、影响、替代方案、计划下线时间。破坏性变更单独分级标注,避免淹没在日常新增里。文档源在仓库内可评审,对外门户从受控内容发布。第三方调用方需要通过开放平台公告或邮件/消息渠道收到通知。

原理流程

  1. 每次接口变更同步更新 changelog 条目。
  2. 分类:新增、增强、修复、废弃、移除。
  3. 破坏性变更标注影响范围与迁移指南。
  4. 对外门户与 SDK 说明同步发布。
  5. 下线计划在日志与废弃清单中互相引用。

代码或图示

changelog 条目:
- [新增] avatar 字段,可选,2026-11-19
- [废弃] username 字段,替代 user_name,计划 2027-02 移除
- [破坏性] 无兼容方案的变更需提前公告与兼容期

常见误区

  • 日志只记修复不记契约变更:调用方看不到结构影响。
  • 破坏性变更在普通条目里一笔带过:通知不到位导致线上故障。

追问

  • changelog 放仓库还是门户?答:仓库内维护可评审,门户发布派生内容;不维护两份手写副本。
  • 废弃字段的文档说明保留多久?答:至少保留到字段下线后一个观察期,供历史版本排查。

04.4.9.3-083 把 GraphQL 落地与 DTO 版本演进串起来,完整的接口工程流程包含哪些门禁?

一句话结论

完整链路为:类型建模与 derive → 契约产物导出 → 兼容矩阵评审 → 旧样例回放与契约测试 → 灰度发布与观测 → 废弃过渡与下线;每一环都有可核对的检查项,不依赖口头约定。

概念解释

本章把 GraphQL 服务端能力与接口演进规则合并为工程闭环:开发期用库类型与派生宏建模;构建期导出 schema/OpenAPI;评审期过兼容矩阵;测试期回放旧样例与消费者契约;发布期灰度与回滚兜底;维护期废弃清单、changelog 与流量观测。Rust 侧落地时业务服务保持库无关,GraphQL 与 DTO 层做适配。

原理流程

  1. 建模:Object/InputObject/枚举与上下文注入,批量加载解决 N+1。
  2. 防护:复杂度/深度限制、鉴权守卫、错误脱敏与监控。
  3. 产物:导出 SDL/OpenAPI,生成客户端类型与文档。
  4. 门禁:兼容 diff、旧样例回放、契约测试纳入 CI。
  5. 运维:灰度开关、双轨过渡、废弃清单、changelog 与下线复盘。

代码或图示

建模 → 防护(复杂度/鉴权/错误) → 契约产物 → 评审矩阵
  → 回归测试(旧样例/消费者契约) → 灰度发布 → 废弃过渡 → 下线复盘

常见误区

  • 只做开发与发布,缺兼容测试与废弃跟踪:演进问题滞后到线上爆发。
  • 业务逻辑直接绑定 GraphQL 库类型:后续换库或加版本层成本高。

追问

  • 本章内容与前后章节如何衔接?答:序列化细节见 04.4.9.1,校验与 OpenAPI 生成见 04.4.9.2;缓存与后台任务见 04.4.10。
  • 哪些行为需要在原型中验证后固化?答:订阅传输、dataloader 批处理、feature 清单与错误扩展写法,以 docs.rs 当前版本为准,不确定项标注待确认。