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

06.8.5.1 gRPC-Kotlin 与 GraphQL-Kotlin

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.8 Kotlin 后端 / 06.8.5 服务端配套与工程实践

本节要解决的问题

  • gRPC-Kotlin:proto 代码生成、协程 Stub、四种流式 RPC、拦截器、错误状态、与 Ktor/Spring 集成及线程模型在 Kotlin 侧的落地。
  • GraphQL-Kotlin:Schema 生成、DataFetcher、N+1 与 DataLoader、订阅、鉴权与复杂度限制、Federation 的 Kotlin 实现。
  • 只聚焦两个库的 Kotlin 工程落地,HTTP/2、protobuf 编码、GraphQL 查询语言规范仅作简短铺垫;版本基线 Ktor 3.x、Kotlin 2.x,不确定依赖坐标与 API 标「待确认」。

06.8.5.1-001 gRPC-Kotlin 在项目中的定位是什么?

一句话结论

gRPC-Kotlin 是 Kotlin 下基于 protobuf 契约的 RPC 框架:由 proto 生成 Kotlin 客户端 Stub 与服务端基类,协程化调用,适合内部服务间高性能接口;浏览器与公网开放场景通常不直接使用。

概念解释

项目定位是服务到服务的远程调用:契约先行、强类型、多流式语义。Kotlin 侧使用协程 Stub 替代老式 Future/Observer 回调。通用 HTTP/2 与编码规范只作铺垫,本节关注代码生成、Stub 用法与服务端实现。

原理流程

  1. 定义 proto 服务与消息契约。
  2. 构建期生成 Kotlin 客户端/服务端代码。
  3. 服务端实现生成的服务基类。
  4. 客户端通过生成 Stub 发起协程调用。

代码或图示

proto -> 代码生成 -> Stub(客户端)/ CoroutineImplBase(服务端)-> 协程 RPC 调用

常见误区

  • 把 gRPC 当对外 REST 替代:浏览器与公网穿透受限。
  • 手写客户端/服务端消息类:绕过生成代码导致契约漂移。

追问

  • 待确认:gRPC-Kotlin 当前运行时与编译器插件坐标,以官方仓库文档核对。
  • 与 Ktor 如何共存?答:可在同一进程内分别提供 HTTP 与 gRPC 端口,集成方式见后续题目。

06.8.5.1-002 proto 文件中 service、message、rpc 分别描述什么?

一句话结论

message 定义传输数据结构,service 定义服务接口集合,rpc 声明一个方法及其请求/响应类型与流式标注;三者共同构成跨语言 RPC 契约。

概念解释

proto 是契约源文件:消息字段带编号,服务方法绑定输入输出类型。流式语义通过关键字标注在方法上。Kotlin 生成代码按这些定义产出类型与接口,修改契约需遵守兼容规则。

原理流程

  1. 定义请求/响应 message。
  2. 在 service 中声明 rpc 方法。
  3. 标注流式类型(默认一元)。
  4. 生成 Kotlin 代码供两侧使用。

代码或图示

message GetUserRequest { string user_id = 1; }
message UserReply { string name = 1; }

service UserService {
  rpc GetUser(GetUserRequest) returns (UserReply);
}

常见误区

  • 字段不编号或复用编号:兼容与解析出错。
  • proto 只写方法不定义消息:生成代码缺类型。

追问

  • 待确认:项目 proto 存放目录与包名约定,按工程结构核对。
  • 多 proto 互相导入怎么组织?答:按领域拆文件,import 引用公共消息。

06.8.5.1-003 代码生成流程与构建插件如何工作?

一句话结论

构建插件在编译期调用 protobuf 编译器插件,把 .proto 生成 Kotlin(及 Java)Stub、消息类与服务基类;生成代码进入构建产物,源码树通常不手工编辑;插件坐标与版本需与 gRPC-Kotlin 基线匹配。

概念解释

代码生成分两步:protobuf 编译器生成语言特定代码,gRPC Kotlin 插件生成协程 Stub 与服务端接口。生成时机在 Kotlin 编译之前;修改 proto 后重新生成。生成目录位置按构建工具约定,不手工修改。

原理流程

  1. 构建脚本配置 proto 源目录与插件版本。
  2. 编译前运行代码生成。
  3. 产出消息类、Stub、服务基类。
  4. 业务代码依赖生成类型编译。

代码或图示

.proto -> protoc + Kotlin gRPC 插件 -> 生成消息/Stub/基类 -> 业务编译引用

常见误区

  • 手工改生成代码:下次生成被覆盖。
  • 插件版本与运行时不匹配:Stub 接口对不上。

追问

  • 待确认:Gradle/Maven 中 protobuf 与 gRPC-Kotlin 插件的确切坐标,以官方示例仓库核对。
  • 生成代码要提交版本库吗?答:一般不提交,由构建期生成;按项目约定核对。

06.8.5.1-004 生成了哪些 Kotlin 类型?

一句话结论

通常生成:消息数据类(带字段与构造器)、客户端协程 Stub 类、服务端抽象基类;流式方法对应挂起函数或流收发接口;类型名按 proto 包与消息名映射,具体类名以生成器规则为准。

概念解释

消息类承载请求响应数据;Stub 供客户端调用;基类供服务端继承实现。一元方法在协程 Stub 上是挂起函数,流式方法暴露流收发接口。生成类型不可手写,契约变更通过重新生成反映。

原理流程

  1. message -> 生成 Kotlin 消息类型。
  2. service -> 生成客户端 Stub。
  3. service -> 生成服务端基类。
  4. 流式 rpc -> 对应流收发抽象。

代码或图示

生成产物:消息类 / CoroutineStub / 服务端 ImplBase / 流式收发接口

常见误区

  • 凭记忆假设生成类名后缀:应以实际生成源码为准。
  • 业务层直接改消息类字段:下次生成丢失。

追问

  • 待确认:Kotlin 生成代码的命名与继承结构,以一次实际生成产物核对。
  • Java 与 Kotlin 生成代码能共存吗?答:按插件配置决定,混用时核对兼容。

06.8.5.1-005 四种 RPC 类型分别是什么?

一句话结论

一元(unary)一请求一响应;服务端流一请求多响应;客户端流多请求一响应;双向流多请求多响应;四种语义在 proto 方法上用 stream 标注,Kotlin 侧分别对应挂起函数与流收发。

概念解释

流式语义决定消息边界与调用模型。一元最简单;服务端流适合推送列表/增量;客户端流适合批量上报;双向流适合双向持续交互。选型按消息方向与实时性,不为流式而流式。

原理流程

  1. 按交互方向选 rpc 类型。
  2. proto 标注 stream 位置。
  3. 生成对应协程/流接口。
  4. 服务端与客户端按流模型收发。

代码或图示

rpc Unary (Req) returns (Reply);
rpc ServerStream (Req) returns (stream Reply);
rpc ClientStream (stream Req) returns (Reply);
rpc Bidi (stream Req) returns (stream Reply);

常见误区

  • 用一元轮询模拟服务端流:实时性与开销不佳。
  • 双向流里混用一次性请求语义:会话边界混乱。

追问

  • 待确认:Kotlin 流式 Stub 的收发 API 形式(通道/ Flow),以生成代码与文档核对。
  • 流能中途取消吗?答:协程取消传播,见后续题目。

06.8.5.1-006 Kotlin coroutine Stub 模型是什么?

一句话结论

gRPC-Kotlin 客户端提供协程 Stub:RPC 方法为挂起函数或基于 Flow/通道的流收发,调用在协程内挂起等待响应,不阻塞线程;服务端实现同样以协程方式处理请求。

概念解释

协程模型替代旧式回调 Observer:一元方法 suspend 返回响应;流式方法通过流通道收发。调用方在自己的协程作用域内发起,取消随作用域传播。这是 Kotlin 侧相对 Java gRPC 客户端的主要差异。

原理流程

  1. 在协程内调用 Stub 方法。
  2. 一元挂起等待响应返回。
  3. 流式通过通道/Flow 收发消息。
  4. 协程取消时 RPC 随之取消。

代码或图示

// 示意:一元调用挂起函数
val reply = stub.getUser(request)

常见误区

  • 在阻塞线程里强等协程结果:抵消协程模型收益。
  • 流式调用不管理协程作用域:连接泄漏。

追问

  • 待确认:coroutine Stub 类名与流式 Flow 适配方式,以生成代码核对。
  • 旧式 stub 仍可用吗?答:按版本保留情况核对,新项目优先协程 Stub。

06.8.5.1-007 服务端实现接口怎么写?

一句话结论

继承生成的服务端基类,实现每个 rpc 方法;一元方法返回响应,流式方法实现流收发;实现类注册到 gRPC 服务端绑定服务;方法内可访问元数据与上下文,异常按状态抛出。

概念解释

服务端实现是生成基类的子类,方法签名与 proto 契约一致。业务逻辑在方法内执行,返回消息或操作流。多个服务实现可注册到同一端口。实现类依赖注入按项目 DI 组织。

原理流程

  1. 继承生成的 ImplBase。
  2. 实现 rpc 方法逻辑。
  3. 构造服务实例并绑定到服务端。
  4. 启动 gRPC 端口接收调用。

代码或图示

class UserServiceImpl : UserServiceCoroutineImplBase() {
    override suspend fun getUser(request: GetUserRequest): UserReply {
        // 业务逻辑
        return UserReply.newBuilder().setName("Ann").build()
    }
}

常见误区

  • 方法签名与生成基类不匹配:编译失败。
  • 服务实现未注册:客户端调用无服务端响应。

追问

  • 待确认:Kotlin 服务端基类命名与构造方式,以生成代码核对。
  • 依赖注入到实现类怎么做?答:构造器注入,服务端装配时传入实例。

06.8.5.1-008 消息字段编号与兼容性规则是什么?

一句话结论

每个字段有唯一编号,编号在消息演进中不可复用;新增字段用新编号,删除字段保留编号预留;编号是 wire 格式标识,改名不影响兼容,复用或改类型会破坏解析。

概念解释

protobuf 兼容靠字段编号而非字段名。演进规则:可加字段(带默认值语义)、可删除字段但保留编号不复用、不改字段编号与类型。Kotlin 侧生成代码随契约更新,两侧版本需兼容。

原理流程

  1. 初始定义字段编号。
  2. 新增字段分配新编号。
  3. 废弃字段标记保留编号。
  4. 跨版本部署时按规则保证旧端可解析。

代码或图示

message UserReply {
  string name = 1;
  int32 age = 2;
  // reserved 3;  // 废弃字段编号预留
}

常见误区

  • 删除字段后把编号给新字段:旧数据解析错乱。
  • 字段类型直接改窄/改宽:不兼容。

追问

  • 待确认:项目 proto 兼容评审规则,按工程约定核对。
  • oneof 字段兼容注意什么?答:成员编号唯一,演进不轻易调换成员。

06.8.5.1-009 标量类型如何映射到 Kotlin 类型?

一句话结论

proto 标量(int32/int64/string/bool/double 等)按生成规则映射到 Kotlin 对应类型;数值有无符号与 32/64 位区分,字符串映射 String;具体可空性与默认值按生成器规则,以实际生成代码核对。

概念解释

类型映射影响业务代码写法:64 位整数映射 Long,字符串映射 String,字节数组映射字节类型。proto 有默认值语义,Kotlin 侧可空性需看生成实现。跨语言契约只依赖 proto 类型,不依赖 Kotlin 特有类型。

原理流程

  1. proto 声明标量类型。
  2. 生成 Kotlin 字段与构造器。
  3. 业务按映射类型读写。
  4. 序列化按 wire 格式编码。

代码或图示

int32 -> Int(示意) / int64 -> Long / string -> String / bool -> Boolean
具体可空性以生成代码为准

常见误区

  • 把 Kotlin 集合类型写进 proto:契约语言无关,需用 repeated/map 表达。
  • 忽略 64 位边界:金额等数值用合适整数类型。

追问

  • 待确认:各标量在 gRPC-Kotlin 生成代码中的精确 Kotlin 类型与可空性,以生成产物核对。
  • 金额字段用什么类型?答:按契约约定用整数分或高精度类型,不用 double 表达金额。

06.8.5.1-010 enum、oneof、map、repeated 如何映射?

一句话结论

repeated 映射为列表,map 映射为字典,enum 映射为枚举类型,oneof 映射为互斥的 sealed/联合结构;具体 Kotlin 形态以生成器规则为准,业务按生成 API 取值与判分支。

概念解释

复合结构在契约语言无关前提下表达集合、映射、枚举与互斥选择。oneof 保证同一时刻只有一个成员被设置。生成代码提供取值与成员判断 API;变更这些结构同样受兼容规则约束。

原理流程

  1. proto 声明 repeated/map/enum/oneof。
  2. 生成对应 Kotlin 集合/枚举/联合类型。
  3. 业务按生成 API 读写。
  4. 兼容演进保留编号与成员结构。

代码或图示

message Order {
  repeated string tags = 1;
  map<string, string> attrs = 2;
  enum Status { NEW = 0; PAID = 1; }
  oneof Pay { string card = 3; string voucher = 4; }
}

常见误区

  • oneof 同时设置两个成员:语义互斥,行为未定义。
  • map 当有序结构使用:map 不保证顺序。

追问

  • 待确认:oneof 在 Kotlin 生成代码中的 sealed 形态与访问器,以生成产物核对。
  • 枚举新增值旧端如何处理?答:未知枚举值按预留/默认策略解析,兼容设计需考虑。

06.8.5.1-011 proto 生成插件坐标与版本有哪些待核对点?

一句话结论

接入前核对:protobuf 编译器版本、gRPC-Kotlin 生成插件坐标与版本、运行时依赖版本与 Kotlin 基线匹配;不确定坐标标待确认,以官方示例仓库与依赖仓库为准,不编造版本号。

概念解释

版本错配会导致 Stub 接口不一致或编译失败。核对矩阵:protoc 版本、Kotlin 插件、gRPC 运行时、Kotlin 语言版本。项目内统一版本管理,不各处引入不同大版本。

原理流程

  1. 查官方示例确认插件与运行时坐标。
  2. 对齐 Kotlin 与 gRPC 基线版本。
  3. 构建脚本配置 proto 源目录。
  4. 生成编译验证 Stub 与基类可引用。

代码或图示

核对矩阵:protoc 版本 / Kotlin 生成插件 / gRPC 运行时 / Kotlin 语言版本

常见误区

  • 凭记忆写插件版本:与基线不兼容。
  • 只引运行时不引生成插件:编译期无代码产物。

追问

  • 待确认:gRPC-Kotlin 官方仓库的 Gradle/Maven 配置示例,以仓库文档为准。
  • 版本升级先验证什么?答:重新生成后编译通过,一元与流式调用回归。

06.8.5.1-012 生成代码纳入版本管理吗?

一句话结论

生成代码通常不提交版本库,由构建期生成;少数离线构建或特定流程会提交生成物,按项目约定执行;无论哪种方式都不手工编辑生成代码,契约变更通过 proto 与重新生成反映。

概念解释

不提交生成物可避免差异冲突,代价是构建依赖生成工具。提交生成物便于离线构建但需同步生成流程。判断标准是项目构建约定,不是个人偏好。生成目录在 .gitignore 或构建配置中明确。

原理流程

  1. 项目约定生成物是否入库。
  2. 构建脚本配置生成目录。
  3. proto 变更触发重新生成。
  4. 评审时检查生成产物差异是否符合预期。

代码或图示

默认:构建期生成,不入库
例外:离线构建流程可提交,但禁止手改

常见误区

  • 手改生成代码后提交:下次生成被覆盖。
  • 生成物入库却不更新:契约与代码漂移。

追问

  • 待确认:项目生成物入库约定,按仓库 .gitignore 与构建配置核对。
  • CI 环境生成依赖什么?答:构建镜像内置 protoc 与插件,保证可重复生成。

06.8.5.1-013 构建期代码生成在什么时机执行?

一句话结论

代码生成在 Kotlin 编译之前完成,属于构建预处理任务;proto 变更触发重新生成,增量构建只重编受影响代码;生成任务失败会阻断编译,保证 Stub 与契约同步。

概念解释

构建流水线:生成任务 -> 编译业务代码 -> 测试打包。生成输出进入编译源集。增量判断基于 proto 源文件变化。本地与 CI 生成配置一致,避免环境差异。

原理流程

  1. 构建启动执行 proto 生成任务。
  2. 产出 Stub/消息/基类到生成目录。
  3. Kotlin 编译引用生成类型。
  4. 后续测试与打包。

代码或图示

构建:proto 生成 -> 编译 -> 测试 -> 打包

常见误区

  • 生成任务在编译后执行:业务代码找不到类型。
  • 本地手动生成未进构建流程:CI 产物不一致。

追问

  • 待确认:所用构建工具的生成任务接入方式,按工程构建脚本核对。
  • 生成目录冲突怎么处理?答:隔离生成源集,不与手写源码混放。

06.8.5.1-014 proto 包名与 Kotlin 包名如何对应?

一句话结论

proto package 与 Kotlin 生成包通过生成配置映射;生成类型所在包以配置与 proto 声明为准;业务 import 按生成包组织,避免跨包乱引用;多模块 proto 包名按领域划分。

概念解释

包名影响生成类的全限定名与 import。配置可指定 Kotlin 包覆盖策略。模块间引用通过 proto import 与生成包解析。包名稳定后不随意变更,否则引用全断裂。

原理流程

  1. proto 声明 package。
  2. 生成配置映射 Kotlin 包。
  3. 生成类型落入对应包。
  4. 业务代码按包 import。

代码或图示

package com.example.user;

常见误区

  • 包名与模块职责不符:引用关系混乱。
  • 变更包名不更新生成引用:编译断裂。

追问

  • 待确认:生成器是否支持 Kotlin 包名覆盖配置,以插件文档核对。
  • 多模块 proto 共享消息放哪?答:公共 proto 模块,独立包名引用。

06.8.5.1-015 消息默认值与必填语义如何理解?

一句话结论

proto 字段有语言无关默认值(数值 0、字符串空、false 等),消息层没有强制必填标记;必填校验在应用层完成,缺失字段按默认值解析;不要把默认值当成「已填写」的可信信号。

概念解释

proto3 字段不存在 required 语义(历史 required 已弃用),字段是否必填由接口契约文档与服务端校验保证。Kotlin 侧读取到默认值时无法区分「未传」与「传了默认值」,需要区分时用包装类型或显式标记。

原理流程

  1. 客户端未填字段使用默认值编码省略。
  2. 服务端解析得到类型默认值。
  3. 应用层校验必填业务字段。
  4. 需区分缺失时用可空包装或标记字段。

代码或图示

默认值:0 / "" / false / 空集合
必填:服务端业务校验,不依赖 proto 标记

常见误区

  • 依赖 proto 必填语法保证校验:proto3 不提供该语义。
  • 把默认值当用户显式传入:业务判断错误。

追问

  • 待确认:gRPC-Kotlin 生成代码对缺失字段的可空表达,以产物核对。
  • 可选消息字段怎么表达存在性?答:用消息类型包装或 oneof,按契约设计。

06.8.5.1-016 嵌套消息与导入依赖如何组织?

一句话结论

消息可在消息内嵌套定义,也可在独立 proto 中定义后 import 引用;公共消息抽到共享 proto 模块,服务契约文件只引用所需类型;导入路径按构建配置解析,循环依赖需避免。

概念解释

组织原则:领域内聚、公共复用。嵌套消息适合仅被父消息使用;独立文件适合跨服务复用。import 引入其他 proto 的消息类型。共享 proto 版本随消费方兼容演进。

原理流程

  1. 公共消息建独立 proto。
  2. 服务 proto import 公共类型。
  3. 生成代码按包引用。
  4. 公共契约变更通知消费方。

代码或图示

import "common/address.proto";

message Order { Address address = 1; }

常见误区

  • 所有消息塞一个 proto:文件膨胀、复用困难。
  • 服务间共享私有消息:耦合边界不清。

追问

  • 待确认:项目 proto 模块划分,按仓库结构核对。
  • 循环 import 怎么处理?答:抽取公共底层消息层,打破环依赖。

06.8.5.1-017 版本演进与向后兼容规则有哪些?

一句话结论

服务端与客户端可滚动升级:新增字段/方法向后兼容,删除与改类型属破坏性变更;旧客户端不识别新字段时忽略未知字段;破坏性变更新开服务方法或版本号,不原地改契约。

概念解释

兼容方向:新服务端接收旧客户端消息(缺新字段用默认值),旧客户端接收新服务端消息(忽略未知字段)。演进清单:可加不可复用编号、不改类型、枚举新增值预留兼容。灰度期间新旧版本共存。

原理流程

  1. 变更评审兼容级别。
  2. 兼容变更直接发版,滚动升级。
  3. 破坏性变更走新版本接口。
  4. 观察旧版本调用量后下线旧契约。

代码或图示

兼容:加字段/加方法 / 忽略未知字段
破坏:删字段复用编号 / 改类型 / 改方法签名 -> 新版本

常见误区

  • 滚动发布期间两侧版本不匹配:依赖未兼容变更断裂。
  • 枚举新增值未考虑旧端解析:未知值处理缺失。

追问

  • 待确认:项目接口版本策略,按架构约定核对。
  • 字段废弃流程?答:标注废弃、双写过渡、确认无消费后删除并预留编号。

06.8.5.1-018 gRPC 与 REST/HTTP 接口如何在同一服务共存?

一句话结论

同一 JVM 进程可同时监听 HTTP(Ktor)与 gRPC 端口,分别注册服务;面向外部浏览器/开放 API 走 HTTP,内部服务调用走 gRPC;端口、服务注册与健康检查分别配置,进程资源共享但协议隔离。

概念解释

共存目的:对外灵活、对内高性能。两个协议栈各自绑定端口与服务实例。共享业务服务层,控制器/Stub 适配器分别转换 DTO。部署清单暴露所需端口,内部 gRPC 端口不对外。

原理流程

  1. 装配共享业务服务。
  2. 启动 Ktor HTTP 端口与 gRPC 端口。
  3. HTTP 适配器与 gRPC 实现类调用同一服务层。
  4. 网关/服务发现区分两类入口。

代码或图示

业务服务层 <- HTTP 适配器(Ktor)
业务服务层 <- gRPC 服务实现

常见误区

  • gRPC 端口暴露公网:协议与穿透受限且攻击面扩大。
  • 两套接口各写一套业务逻辑:维护漂移。

追问

  • 待确认:gRPC-Kotlin 与 Ktor 在同进程启动的集成方式,以官方示例核对。
  • 端口冲突怎么避免?答:编排配置分别指定端口,健康检查分别暴露。

06.8.5.1-019 一元调用在协程中如何发起?

一句话结论

在协程内调用 Stub 的挂起方法传入请求消息,挂起等待响应消息返回;异常以状态异常形式抛出;调用绑定当前协程作用域,取消时 RPC 一并取消。

概念解释

一元调用对应一次请求响应往返。Stub 方法是 suspend 函数,不需要回调注册。并发发起可用 async 并行多个一元调用。超时由调用上下文或 Stub 配置控制。

原理流程

  1. 协程内构造请求消息。
  2. 调用 Stub 挂起方法。
  3. 等待响应或状态异常。
  4. 取消随协程传播取消 RPC。

代码或图示

val reply = stub.getUser(GetUserRequest.newBuilder().setUserId("u1").build())

常见误区

  • 阻塞等待挂起结果:占用线程且不可取消。
  • 不处理状态异常:下游失败冒泡成未捕获错误。

追问

  • 待确认:一元 Stub 方法的确切签名(请求参数/响应类型),以生成代码核对。
  • 并发多个调用怎么做?答:coroutineScope 内 async 并行,await 组合。

06.8.5.1-020 服务端流如何消费?

一句话结论

客户端调用服务端流方法后,通过返回的流通道/Flow 逐条接收响应;服务端在流内陆续发消息;接收循环随取消终止,流结束以正常完成或错误状态结束。

概念解释

服务端流一次请求多条响应,适合列表分段、增量推送。客户端按流消费,不需要为每条消息单独发请求。背压与取消依流实现传播。消息顺序按发送顺序到达。

原理流程

  1. 发起服务端流调用。
  2. 服务端写入多条响应。
  3. 客户端流循环逐条消费。
  4. 流完成或异常结束。

代码或图示

// 示意:遍历服务端流(具体接收 API 以生成代码为准)
stub.listOrders(request).collect { reply -> /* ... */ }

常见误区

  • 把服务端流当一元拿单个响应:遗漏后续消息。
  • 接收循环不响应取消:流泄漏。

追问

  • 待确认:服务端流返回类型(Flow/通道)与收集 API,以生成代码核对。
  • 流中途出错怎么感知?答:流抛出状态异常,在收集层捕获分类处理。

06.8.5.1-021 客户端流如何发送并收尾?

一句话结论

客户端流方法由客户端写入多条请求消息,写完后关闭发送通道,服务端汇总处理后返回单个响应;发送与收尾按流接口顺序操作,未正确收尾会导致服务端一直等待。

概念解释

适合批量上报、批量上传。客户端通过发送通道写入消息,完成后通知结束;服务端在收到完成信号后处理并返回响应。取消连接同样终止流。消息顺序按写入顺序到达。

原理流程

  1. 调用客户端流方法获得发送通道。
  2. 逐条写入请求消息。
  3. 关闭发送表示完成。
  4. 等待服务端汇总响应。

代码或图示

// 示意:客户端流写入并收尾(API 以生成代码为准)
val response = stub.uploadRecords { channel ->
    records.forEach { channel.send(it) }
}

常见误区

  • 忘记关闭发送通道:服务端阻塞等更多消息。
  • 发送后继续写已关闭通道:流异常。

追问

  • 待确认:客户端流发送通道与收尾 API,以生成代码核对。
  • 批量失败如何部分处理?答:协议设计逐条结果或汇总状态,按契约约定。

06.8.5.1-022 双向流会话模型是什么?

一句话结论

双向流建立一条持续会话,双方可随时发送消息,互不等待对方单条响应;消息在同一流内双向流动,会话随取消或结束关闭;适合实时双向交互(聊天、同步、推送协作)。

概念解释

双向流不是两个独立一元调用,而是一条会话通道。读写可在不同协程并行;消息顺序各自独立。生命周期管理:建立、收发、取消/结束。协议层定义消息类型与交互约定。

原理流程

  1. 调用双向流方法建立会话。
  2. 读协程接收对端消息,写协程发送本地消息。
  3. 双方按协议交互。
  4. 取消或正常结束关闭会话。

代码或图示

双向流:同一会话通道,读协程 + 写协程并行,取消即关闭

常见误区

  • 读写在单协程顺序耦合:发送被接收等待卡住。
  • 不管理会话协程:连接泄漏。

追问

  • 待确认:双向流读写通道 API 与协程组织方式,以生成代码核对。
  • 心跳在双向流里怎么做?答:协议定义心跳消息类型,空闲时互发维持会话。

06.8.5.1-023 旧式 Observer/StreamObserver 模型与协程 Stub 有何区别?

一句话结论

旧式模型用回调观察者接收消息与完成/错误回调;协程 Stub 用挂起函数与 Flow/通道表达相同语义,代码顺序结构化、取消随协程传播;新项目优先协程 Stub,遗留代码兼容旧模型(保留情况待确认)。

概念解释

差异本质:回调驱动 vs 协程结构化并发。旧式回调需要注册 onNext/onError/onCompleted,状态管理分散;协程模型可直接顺序编写、作用域取消、异常结构化传播。两套模型能力对应但写法不同。

原理流程

  1. 旧模型注册观察者回调。
  2. 消息与完成事件触发回调。
  3. 协程模型挂起/Flow 收集表达同等流程。
  4. 迁移时按流式语义逐方法改写。

代码或图示

旧式:StreamObserver 回调(onNext/onError/onCompleted)
协程:suspend 函数 / Flow 收集 / 结构化取消

常见误区

  • 在协程代码里套旧式回调:取消与异常传播断裂。
  • 假设两套 Stub 可混用传递:接口实现需匹配生成类型。

追问

  • 待确认:gRPC-Kotlin 对旧式 Stub 的保留状态,以版本文档核对。
  • 迁移风险点?答:流式回调状态机改写为流收集,需覆盖取消与异常路径。

06.8.5.1-024 流式调用的背压如何处理?

一句话结论

gRPC 流基于 HTTP/2 流控传递背压,消费慢时对端发送速率被限制;应用层批量大小、队列深度与消费协程决定实际吞吐;业务协议需定义批量与节流策略,避免无限缓冲。

概念解释

传输层有流控窗口,应用层仍需控制消息堆积。批量加载、有界队列、消费速率匹配生产速率。慢消费者不应拖垮发送方线程。背压体现为流暂停发送,应用层可观测积压。

原理流程

  1. 生产速率与消费速率匹配评估。
  2. 有界队列缓冲,溢出按策略丢弃/阻塞。
  3. 传输流控限制过快发送。
  4. 监控积压与延迟调整批量。

代码或图示

背压:传输流控 + 应用有界队列 + 批量节流

常见误区

  • 应用层无界缓冲:慢消费者导致内存膨胀。
  • 忽略批量大小:单条消息开销放大。

追问

  • 待确认:gRPC-Kotlin 流实现是否暴露队列与背压指标,以运行时文档核对。
  • 关键消息能丢吗?答:按业务分级,关键消息需确认机制。

06.8.5.1-025 协程取消如何传播到 RPC?

一句话结论

客户端协程取消时,对应的 RPC 调用随之取消并通知服务端;服务端处理协程收到取消信号应终止工作并释放资源;取消是协作式的,阻塞不可中断代码仍需隔离处理。

概念解释

结构化并发保证调用链取消一致:请求超时、客户端断开、上游取消都会传播到下游 RPC。服务端收到取消后停止下游调用与写操作。资源释放走 finally 路径。

原理流程

  1. 调用方协程被取消。
  2. RPC 发送取消帧到对端。
  3. 服务端处理协程收到取消。
  4. 清理资源,流终止。

代码或图示

try {
    stub.getUser(request)
} finally {
    // 释放本次调用资源
}

常见误区

  • 服务端忽略取消继续跑:占用计算与下游资源。
  • 阻塞不可中断循环:取消信号延迟生效。

追问

  • 待确认:服务端取消信号在 Kotlin 实现中的可访问方式,以运行时文档核对。
  • 取消后能继续写响应吗?答:流已取消,写出会失败,应终止处理。

06.8.5.1-026 响应式流与协程之间如何转换?

一句话结论

项目中协程优先;需要对接响应式类型(Flow 之外的 Reactive Streams Publisher 等)时通过适配桥接互转;转换层保留取消与背压语义,不把响应式回调硬塞进协程代码。

概念解释

gRPC-Kotlin 原生倾向协程/Flow;既有项目可能用响应式库。桥接操作把订阅关系转为协程收集或反向转换。边界清晰:核心业务用协程,适配层隔离响应式类型。

原理流程

  1. 识别外部响应式类型边界。
  2. 用官方/适配桥接转换为 Flow/挂起调用。
  3. 业务协程内处理。
  4. 回包方向反向适配。

代码或图示

响应式 Publisher <-> Flow(适配桥接)-> 协程业务处理

常见误区

  • 转换时丢失取消传播:上游取消不到下游。
  • 在业务核心混用两种模型:状态管理混乱。

追问

  • 待确认:项目使用的响应式库与 gRPC-Kotlin 桥接支持,按依赖核对。
  • 双向流对接响应式观察者怎么做?答:在适配层分别桥接读写通道。

06.8.5.1-027 超时与 Deadline 如何设置?

一句话结论

RPC 调用可设置截止时间(deadline),到期未完成自动取消;超时在客户端调用上下文或 Stub 配置设定;服务端可读取剩余时间做快速失败;不同方法按 SLA 分级设限,不使用无限等待。

概念解释

Deadline 是跨进程的时间预算,从调用发起延续到服务端处理。超时避免长尾调用占用连接与线程。服务端不应超过剩余预算继续重活。超时与重试配合,总时长受上游约束。

原理流程

  1. 调用侧设定 deadline/超时。
  2. 到期未完成取消 RPC。
  3. 服务端可读取剩余时间判断是否继续。
  4. 超时映射为对应状态异常。

代码或图示

// 示意:调用级超时配置(具体 API 以 Stub/上下文文档为准)
withTimeout(2_000) { stub.getUser(request) }

常见误区

  • 不设超时:下游挂起拖垮线程与连接。
  • 超时时间大于上游网关:请求已断而服务端仍在跑。

追问

  • 待确认:gRPC-Kotlin deadline 配置入口与时间源约定,以官方文档核对。
  • 超时异常映射什么状态?答:超时对应超时状态码,见错误码题目。

06.8.5.1-028 元数据(Metadata)如何传递?

一句话结论

元数据是随调用传递的键值对(类似 HTTP 头),用于鉴权令牌、追踪标识、请求租户等;客户端调用时附加,服务端从调用上下文读取;二进制与文本值类型有区分,敏感值不进日志。

概念解释

Metadata 跨进程调用附带,不放进消息体。用途:认证凭据、trace 标识、租户、请求级别开关。服务端读取后放入业务上下文。元数据大小与数量受协议限制,规范命名。

原理流程

  1. 客户端构造元数据附加到调用。
  2. 元数据随请求帧传递。
  3. 服务端从上下文读取键值。
  4. 业务鉴权/追踪使用。

代码或图示

Metadata:鉴权令牌 / trace-id / 租户标识 / 开关

常见误区

  • 把大对象放元数据:应走消息体。
  • 元数据记录日志:凭据泄露风险。

追问

  • 待确认:gRPC-Kotlin 元数据读写 API 与类型区分,以官方文档核对。
  • 元数据能在拦截器统一处理吗?答:可以,客户端/服务端拦截器读取注入。

06.8.5.1-029 客户端 Stub 类型与配置如何组织?

一句话结论

Stub 由通道创建,分为协程 Stub 与旧式 Stub(按版本);Stub 配置包含元数据、超时、拦截器等;Stub 实例可复用,对应同一通道;不同下游/策略可创建独立 Stub 实例。

概念解释

通道代表与服务端的连接,Stub 是通道上的方法代理。Stub 轻量,可复用共享通道。认证与默认元数据在 Stub 或调用层配置。服务隔离:不同下游独立通道与 Stub。

原理流程

  1. 创建通道连接目标服务端。
  2. 由通道生成 Stub。
  3. 配置拦截器、默认元数据与超时。
  4. 业务通过 Stub 发起调用。

代码或图示

// 示意:通道 + Stub(类型名以生成代码为准)
val channel = ManagedChannel.forTarget("host:8080").build()
val stub = UserServiceCoroutineStub(channel)

常见误区

  • 每个调用新建通道:连接无法复用。
  • 多下游共用一个 Stub:元数据与超时互相影响。

追问

  • 待确认:Kotlin 通道工厂与 Stub 构造 API,以官方文档核对。
  • Stub 线程安全吗?答:设计为可并发复用,按运行时文档核对。

06.8.5.1-030 通道(Channel)管理与复用怎么做?

一句话结论

通道是到服务端的长连接,应在应用生命周期内复用,停机时优雅关闭;通道维护连接与复用,不要每次调用新建;通道配置含目标、连接参数与关闭时机;多服务端通过负载均衡通道处理。

概念解释

通道复用减少握手与连接建立开销。通道生命周期绑定应用,停机关闭释放连接。通道断开由重连机制恢复。服务端列表与负载均衡在通道层配置。

原理流程

  1. 应用装配期创建通道。
  2. 业务调用经通道复用连接。
  3. 断线按配置重连。
  4. 停机关闭通道释放资源。

代码或图示

通道:长连接复用 / 断线重连 / 应用停机关闭

常见误区

  • 请求级新建通道:连接与线程泄漏。
  • 通道不关闭:停机残留连接。

追问

  • 待确认:Kotlin 通道关闭方法与优雅停机参数,以运行时文档核对。
  • 通道空闲多久断开?答:按配置与服务端 keepalive 策略核对。

06.8.5.1-031 负载均衡与服务发现如何配合?

一句话结论

gRPC 客户端通道可配置服务端列表与负载均衡策略;配合服务发现解析实例列表;客户端侧均衡在通道层完成,服务端实例健康由健康检查过滤;具体 LB 策略支持度按运行时版本核对。

概念解释

内部服务间调用需要实例选择:固定地址、名称解析或服务发现。负载均衡在客户端通道层分发请求到健康实例。健康状态影响实例剔除。多实例无状态前提下均衡有效。

原理流程

  1. 服务发现解析目标实例列表。
  2. 通道配置 LB 策略与更新机制。
  3. 调用分发到健康实例。
  4. 实例下线从列表剔除。

代码或图示

服务发现 -> 实例列表 -> 通道 LB 策略 -> 健康实例分发

常见误区

  • 写死单实例地址:单点故障。
  • 不剔除不健康实例:请求落到失效节点。

追问

  • 待确认:gRPC-Kotlin 客户端 LB 策略与服务发现集成方式,以运行时文档核对。
  • 与 Ktor 服务端注册如何配合?答:按项目服务发现组件对接,通道配置地址源。

06.8.5.1-032 流式消息的顺序保证如何?

一句话结论

同一流内消息按发送顺序到达对端;不同流/不同调用之间不保证全局顺序;双向流读写各自有序;业务需要全局顺序时自行定义序号并在消费侧排序。

概念解释

顺序保证范围是单条流。并行多个调用或多个流之间消息交错。批量消息若需要按业务顺序处理,协议应带序号或保证同一实体走同一流。重连后顺序需状态恢复。

原理流程

  1. 单流内按发送写入顺序到达。
  2. 多流/并发调用交错到达。
  3. 业务强顺序需求带序号排序。
  4. 重连后按序号补齐去重。

代码或图示

顺序:单流内有序;跨流不保证;强顺序靠协议序号

常见误区

  • 假设并行调用结果按发起顺序返回:到达次序不定。
  • 重连后不按序号去重:消息重复或乱序。

追问

  • 待确认:流重连后的消息恢复机制,按项目协议设计核对。
  • 顺序与性能如何权衡?答:按实体分片到同一流保序,降低全局排序成本。

06.8.5.1-033 客户端拦截器如何工作?

一句话结论

客户端拦截器在调用出站与响应入站之间介入:可附加元数据、记录日志、超时、重试与观测;拦截器按链顺序执行,可修改请求元数据与观察响应状态;通道/Stub 装配时注册。

概念解释

客户端拦截器是出站横切层:认证头注入、trace 透传、指标采集、错误分类。拦截不改变方法契约,只包装调用。多个拦截器形成链,顺序影响包裹层次。

原理流程

  1. 装配期注册客户端拦截器。
  2. 调用出站前拦截处理元数据。
  3. 执行 RPC。
  4. 响应入站后拦截记录/处理。

代码或图示

客户端链:元数据注入 -> 日志/指标 -> RPC -> 响应处理

常见误区

  • 拦截器内持有请求级可变状态:并发调用污染。
  • 拦截器吞掉异常不记录:失败原因丢失。

追问

  • 待确认:gRPC-Kotlin 客户端拦截器接口签名,以官方文档核对。
  • 重试放拦截器还是 Stub 层?答:按能力边界配置,注意幂等前提。

06.8.5.1-034 服务端拦截器如何工作?

一句话结论

服务端拦截器在方法执行前/后介入:读取元数据做鉴权、记录日志与指标、校验上下文;拦截器可拒绝调用返回错误状态;注册到服务端绑定服务链上,按顺序执行。

概念解释

服务端拦截器是入站横切层:认证、租户解析、trace 关联、访问日志。鉴权拒绝直接返回状态,不进入业务实现。多个拦截器顺序形成前置处理链。

原理流程

  1. 装配服务端时注册拦截器。
  2. 请求到达先经拦截链读取元数据。
  3. 通过后调用业务实现。
  4. 响应返回前拦截记录结果。

代码或图示

服务端链:元数据鉴权 -> 上下文注入 -> 业务实现 -> 结果记录

常见误区

  • 鉴权放业务方法内:各实现重复且易漏。
  • 拦截器读取大消息体:流被提前消费。

追问

  • 待确认:gRPC-Kotlin 服务端拦截器接口与上下文访问方式,以文档核对。
  • 拦截器能改请求消息吗?答:一般读取元数据为主,消息修改需在协议层设计。

06.8.5.1-035 拦截器可以做哪些横切工作?

一句话结论

常见横切:认证元数据校验、主体/租户注入、trace 标识透传、访问日志、指标计时、错误归一、元数据黑白名单;业务鉴权与数据归属仍在服务实现层完成,拦截器不替代业务授权。

概念解释

拦截器适合与具体方法无关的通用处理。角色:把协议元数据转成业务上下文,记录调用观测。方法级权限、数据归属判断留在业务层。拦截器职责保持单薄,便于测试与复用。

原理流程

  1. 识别通用横切能力。
  2. 客户端/服务端拦截器分别实现出站入站处理。
  3. 注入业务上下文。
  4. 观测记录指标与日志。

代码或图示

横切:鉴权 / 上下文 / trace / 日志 / 指标 / 错误归一
业务层:方法权限 / 数据归属

常见误区

  • 在拦截器写业务规则:与具体方法耦合,复用性差。
  • 拦截器内做重 IO:拖慢调用链。

追问

  • 待确认:拦截器间顺序配置方式,以运行时文档核对。
  • 上下文如何传给业务实现?答:经调用上下文或构造器注入,按项目 DI 组织。

06.8.5.1-036 gRPC 错误码体系(Status.Code)是什么?

一句话结论

gRPC 用标准化状态码表达结果类别:OK、取消、超时、无效参数、未认证、权限不足、未找到、冲突、不可用、内部错误等;业务异常映射到对应码,客户端按码分类处理,不依赖错误字符串判断。

概念解释

状态码跨语言统一,错误消息供排查。常见映射:参数非法 INVALID_ARGUMENT、未认证 UNAUTHENTICATED、无权限 PERMISSION_DENIED、资源不存在 NOT_FOUND、下游不可用 UNAVAILABLE、未预期错误 INTERNAL。码语义比消息稳定,客户端分支按码处理。

原理流程

  1. 服务端识别错误类别。
  2. 构造对应 Status 与消息。
  3. 以状态异常返回客户端。
  4. 客户端按码分类:重试/降级/提示。

代码或图示

INVALID_ARGUMENT -> 4xx 类客户端错误
UNAUTHENTICATED / PERMISSION_DENIED -> 认证授权
NOT_FOUND / ALREADY_EXISTS -> 资源状态
UNAVAILABLE / DEADLINE_EXCEEDED -> 可重试类
INTERNAL -> 未预期系统错误

常见误区

  • 所有失败都返回 INTERNAL:客户端无法区分可重试与参数错误。
  • 按错误消息文本分支:文案改动即失效。

追问

  • 待确认:gRPC-Kotlin 中状态码枚举与构造方式,以运行时文档核对。
  • 业务细分错误怎么携带?答:状态消息或错误详情结构,按契约定义,不塞进状态码。

06.8.5.1-037 StatusException 与 StatusRuntimeException 有何区别?

一句话结论

两者都携带 gRPC Status,受检/运行时形态不同:Kotlin 侧通常使用运行时异常传播状态错误;具体类型名称与继承关系以运行时版本为准,未核对前标待确认,业务代码按基类捕获。

概念解释

异常类型封装状态码与消息,跨进程序列化为 gRPC 状态。服务端抛出后客户端收到对应异常。捕获时按基类与状态码判断,不依赖具体子类。Kotlin 无受检异常概念,运行时异常更自然。

原理流程

  1. 服务端业务失败构造状态异常。
  2. 运行时捕获并转为 gRPC 状态。
  3. 客户端收到对应异常与码。
  4. 客户端按状态码分类处理。

代码或图示

// 示意:按状态抛出(异常类型以运行时为准)
throw StatusException(Status.NOT_FOUND.withDescription("user missing"))

常见误区

  • 捕获具体子类而漏捕获基类:状态异常分支遗漏。
  • 异常消息回显内部细节:泄露实现信息。

追问

  • 待确认:gRPC-Kotlin 异常类名(StatusException/StatusRuntimeException)与继承关系,以官方文档核对。
  • 异常能携带结构化错误详情吗?答:按运行时支持的详情机制附加,版本能力需核对。

06.8.5.1-038 业务错误如何映射到 gRPC 状态码?

一句话结论

领域异常分类映射标准码:输入校验 -> INVALID_ARGUMENT,未登录 -> UNAUTHENTICATED,越权 -> PERMISSION_DENIED,不存在 -> NOT_FOUND,状态冲突 -> FAILED_PRECONDITION/ALREADY_EXISTS,下游不可用 -> UNAVAILABLE,未预期 -> INTERNAL;映射集中在异常转换层。

概念解释

映射避免业务实现直接构造 gRPC 状态:领域异常 -> 转换层 -> 标准码。错误码与人类消息分离,消息中性。映射规则在一处维护,客户端与服务端对码语义达成契约。

原理流程

  1. 定义领域异常层次与错误码。
  2. 转换层按异常类型映射 gRPC 状态。
  3. 附加中性错误消息。
  4. 未识别异常兜底 INTERNAL 并记录日志。

代码或图示

when (e) {
    is ValidationException -> Status.INVALID_ARGUMENT
    is AuthException -> Status.UNAUTHENTICATED
    is NotFoundException -> Status.NOT_FOUND
    else -> Status.INTERNAL
}

常见误区

  • 服务端实现里随手抛 INTERNAL:客户端无法重试或提示。
  • 映射分散在各方法:规则不一致。

追问

  • 待确认:状态码与 HTTP 状态的对照在网关转换时如何映射,按项目网关约定核对。
  • 枚举类业务错误放哪?答:消息体或错误详情结构,状态码只表达类别。

06.8.5.1-039 异常如何跨进程传播?

一句话结论

服务端异常被 gRPC 运行时捕获,转为状态码与消息随响应返回;客户端收到对应状态异常;堆栈默认不跨进程传播,需要关联时通过 trace 标识在日志侧串联;业务错误详情按契约结构携带。

概念解释

跨进程传播的是状态类别与消息,不是服务端堆栈。客户端只看到状态与消息,服务端堆栈留在服务端日志。trace 元数据贯穿两侧用于排障。未捕获异常兜底为 INTERNAL,避免连接挂起。

原理流程

  1. 服务端方法抛出异常。
  2. 运行时拦截并映射状态。
  3. 响应携带状态码、消息与详情。
  4. 客户端解出状态异常,堆栈在各自日志按 trace 关联。

代码或图示

服务端堆栈 -> 本地日志
状态码 + 消息 + trace-id -> 跨进程
客户端异常 -> 本地日志按 trace 串联

常见误区

  • 把服务端堆栈写进消息返回:泄露内部结构。
  • 异常未被兜底:连接挂起直到超时。

追问

  • 待确认:结构化错误详情跨进程传递的支持方式,以运行时文档核对。
  • 两侧日志如何对齐?答:元数据透传 trace 标识,日志平台按标识检索。

06.8.5.1-040 鉴权元数据如何在 gRPC 调用间传递?

一句话结论

客户端在元数据附加令牌或服务凭据,服务端拦截器读取并校验,构造主体放入调用上下文;元数据在每次调用附带,不通过消息体传递;令牌过期与吊销按认证策略处理,敏感值脱敏日志。

概念解释

gRPC 鉴权位置在拦截层:出站注入凭据,入站校验并解析主体。元数据键名按约定统一。服务端上下文携带主体供业务授权。内部服务凭据与用户令牌可分层传递(传递用户身份 + 服务认证)。

原理流程

  1. 客户端拦截器附加认证元数据。
  2. 服务端拦截器读取校验。
  3. 主体写入调用上下文。
  4. 业务实现按主体授权。

代码或图示

客户端:metadata = { authorization: Bearer ... }
服务端拦截器:校验 -> principal -> 上下文

常见误区

  • 凭据放消息体:每个方法都要重复处理且易漏校验。
  • 服务端只认证不解析主体:授权层拿不到身份。

追问

  • 待确认:上下文存取主体的 API,以运行时文档核对。
  • 多跳服务间身份怎么传?答:用户标识透传 + 各跳服务认证,按信任边界设计。

06.8.5.1-041 gRPC 服务如何与 Ktor 服务端集成?

一句话结论

同一进程内分别启动 Ktor HTTP 引擎与 gRPC 服务端口,共享业务服务层;gRPC 服务实现类调用同一业务 Bean;配置、日志、拦截器分别组织;集成方式以 gRPC-Kotlin 与 Ktor 官方示例为准,标待确认。

概念解释

集成重点:共享业务逻辑而非复制;两条协议栈各自绑定端口与拦截链。DI 容器同时装配 Ktor 路由与 gRPC 实现。健康检查分别覆盖 HTTP 与 gRPC。部署清单暴露所需端口,gRPC 端口内部网络隔离。

原理流程

  1. 装配共享业务服务。
  2. 启动 Ktor HTTP 端口。
  3. 注册并启动 gRPC 服务端口。
  4. 两套适配器调用同一业务层。

代码或图示

共享业务服务
├─ Ktor 路由适配器(HTTP/JSON)
└─ gRPC 服务实现(Protobuf)

常见误区

  • 两套接口各写业务逻辑:规则与数据漂移。
  • gRPC 端口对公网开放:协议穿透与攻击面问题。

追问

  • 待确认:gRPC-Kotlin 服务端在 Ktor 进程内启动的官方集成方式,以示例仓库核对。
  • 端口与线程资源如何隔离?答:按引擎/运行时配置分别评估,共享 JVM 资源配额。

06.8.5.1-042 与 Spring Boot 集成有哪些要点?

一句话结论

gRPC 服务实现可作为 Spring Bean 注入业务依赖,启动时绑定到 gRPC 服务端;客户端 Stub/通道按 Bean 装配;配置走 Spring 配置体系;本节仅作对比提及,Spring 细节见 06.2 分册。

概念解释

集成模式:实现类注册为 Bean,生命周期受容器管理;通道与 Stub 单例复用;配置属性注入拦截器与元数据。Spring 生态的服务发现、拦截器与 gRPC 运行时对接。协程 Stub 与 Spring 异步模型需适配。

原理流程

  1. 实现类声明为 Bean 并注入业务依赖。
  2. 启动生命周期绑定 gRPC 服务端。
  3. 通道/Stub 作为单例 Bean 复用。
  4. 配置与拦截器按容器装配。

代码或图示

Spring 容器:业务 Bean <-> gRPC 实现 Bean / 通道 Stub Bean

常见误区

  • 每次请求新建通道 Bean:连接无法复用。
  • 协程 Stub 被阻塞式调用包裹:线程模型错位。

追问

  • 待确认:gRPC-Kotlin 与 Spring Boot 自动装配支持,以生态组件文档核对。
  • 协程与 Spring 事务边界?答:事务边界在协程作用域内控制,按项目实践核对。

06.8.5.1-043 gRPC-Kotlin 的性能与线程模型如何理解?

一句话结论

基于 HTTP/2 多路复用,单连接并发多个调用;协程 Stub 让请求处理挂起等待 IO 而不占阻塞线程;性能优势来自紧凑编码、长连接复用与并发模型;实际吞吐仍受业务阻塞与下游能力约束。

概念解释

线程模型:连接事件复用 + 协程挂起。消息二进制编码体积小于 JSON。但业务阻塞调用、下游慢响应仍是瓶颈。性能评估以压测为准,不凭框架名称下结论。线程池与协程调度按运行时配置。

原理流程

  1. 单通道多路复用并发调用。
  2. 请求处理协程挂起等待 IO。
  3. 紧凑序列化减少传输体积。
  4. 压测观察吞吐、延迟与资源占用。

代码或图示

并发:HTTP/2 多路复用 + 协程挂起
编码:Protobuf 紧凑二进制
瓶颈:业务阻塞 / 下游响应 / 序列化成本

常见误区

  • 认为 gRPC 天然高性能无瓶颈:阻塞代码仍会拖垮线程。
  • 用短连接调用抵消多路复用优势。

追问

  • 待确认:gRPC-Kotlin 服务端线程池与协程调度配置,以运行时文档核对。
  • 性能对比要控制什么变量?答:报文大小、并发模型、下游一致,分场景压测。

06.8.5.1-044 HTTP/2 多路复用在 Kotlin 侧如何体现?

一句话结论

多路复用在单个 TCP 连接上并发多个独立流,调用互不阻塞;Kotlin 侧体现为同一通道上并发发起多个 Stub 调用;流之间消息交错,顺序保证限于单流;连接建立成本被复用摊薄。

概念解释

HTTP/2 铺垫知识:帧与流的概念。Kotlin 业务不直接操作帧,通过通道与并发 Stub 调用使用多路复用。流的取消、背压在单流内独立。连接复用减少握手与端口占用。

原理流程

  1. 单通道建立 HTTP/2 连接。
  2. 并发调用各自占用独立流。
  3. 流消息在连接上帧交错。
  4. 单流独立取消与背压。

代码或图示

1 连接 N 流:并发调用 / 消息交错 / 单流顺序独立

常见误区

  • 假设跨流消息按调用顺序到达:流之间交错。
  • 为并发调用建多条连接:抵消多路复用意义。

追问

  • 待确认:运行时对流并发数与流控窗口的默认配置,以运行时文档核对。
  • HTTP/1.1 回退场景?答:按部署环境协议支持核对,gRPC 依赖 HTTP/2。

06.8.5.1-045 连接池与长连接如何保持?

一句话结论

通道维持到服务端的长连接并复用,keepalive 配置判断空闲死连接;连接池按目标服务端组织,实例复用通道;断线自动重连;应用停机时关闭通道释放连接,避免泄漏与半开连接堆积。

概念解释

长连接复用减少握手;keepalive 探测识别对端或中间层断开的死连接。池化管理多目标通道。空闲连接存活时间与重连间隔按网络环境配置。半开连接不清理会占用资源并失败。

原理流程

  1. 装配期创建通道并保持。
  2. keepalive 探测空闲连接活性。
  3. 断线按配置重连。
  4. 停机关闭全部通道。

代码或图示

通道复用 + keepalive 探测 + 断线重连 + 停机关闭

常见误区

  • 不配置 keepalive:中间层静默断开后调用失败。
  • 停机不 close 通道:残留连接与线程。

追问

  • 待确认:gRPC-Kotlin keepalive 参数与默认值,以运行时文档核对。
  • 多实例服务端连接怎么分布?答:配合负载均衡通道,见服务发现题目。

06.8.5.1-046 压缩与消息体积如何控制?

一句话结论

gRPC 可配置消息压缩算法(按运行时支持),Protobuf 本身字段编号与编码已较紧凑;大字段、重复数据与大列表是体积主要来源;按消息大小评估压缩收益,流式大对象拆分传输。

概念解释

压缩在消息编码后应用,算法协商在调用层。Protobuf 体积优化:字段编号紧凑、避免冗余字符串、列表批量设计。压缩占用 CPU,小消息收益有限。消息体不放大对象与原始二进制大字段。

原理流程

  1. 评估消息大小分布。
  2. 启用协商压缩(如运行时支持)。
  3. 优化契约字段与批量粒度。
  4. 大对象拆分或走文件传输通道。

代码或图示

体积来源:字段冗余 / 大列表 / 二进制大字段
优化:紧凑契约 / 批量 / 压缩协商

常见误区

  • 把大文件直接塞进消息:超限且阻塞流。
  • 所有消息强行压缩:小消息 CPU 收益不抵成本。

追问

  • 待确认:gRPC-Kotlin 支持的压缩算法与配置入口,以运行时文档核对。
  • 消息大小上限在哪配?答:按运行时接收限制配置,超限错误分类处理。

06.8.5.1-047 Protobuf 序列化性能相对 JSON 如何理解?

一句话结论

Protobuf 二进制紧凑、解析快,字段编号替代键名;JSON 文本可读性好但体积与解析开销更高;序列化性能只是 RPC 整体一环,网络往返与业务处理常是更大瓶颈,选型按契约与生态综合判断。

概念解释

铺垫知识:编码格式差异。Kotlin 侧生成代码直接读写消息类,反射开销低。性能对比需同报文、同并发压测。Protobuf 可读性差,调试需工具解码;JSON 适合人读与开放 API。

原理流程

  1. 同场景压测两种格式编码/解码耗时与体积。
  2. 对比端到端延迟与网络占用。
  3. 评估调试与生态成本。
  4. 按内部 RPC vs 开放接口选型。

代码或图示

Protobuf:二进制紧凑 / 生成代码 / 解析快 / 可读性弱
JSON:文本可读 / 通用生态 / 体积与解析开销较高

常见误区

  • 只比序列化 CPU:忽略网络与业务瓶颈占比。
  • 内部 RPC 也强上 JSON:放弃契约与体积收益。

追问

  • 待确认:项目是否有跨格式性能基线,按压测记录核对。
  • 调试 Protobuf 用什么?答:消息解码工具与日志字段打印,按项目实践。

06.8.5.1-048 健康检查与心跳如何实现?

一句话结论

gRPC 可通过健康检查协议或自定义探活方法上报服务状态;keepalive 维持连接活性;服务端健康纳入编排探针;客户端识别不可用实例并剔除。健康检查不执行重业务逻辑。

概念解释

健康检查两层:连接活性(keepalive)与服务就绪(健康状态)。就绪依赖下游可达、初始化完成。探针接口轻量快速。实例不健康从负载均衡列表剔除。具体健康协议支持度按运行时版本核对。

原理流程

  1. 配置 keepalive 检测连接。
  2. 实现健康状态上报/探活方法。
  3. 编排探针读取健康状态。
  4. 不健康实例被剔除。

代码或图示

keepalive:连接活性
健康检查:依赖就绪 / 实例可服务状态

常见误区

  • 健康检查查全部重依赖:抖动误判不健康。
  • 只查进程存活不查依赖:流量打到不可用实例。

追问

  • 待确认:gRPC-Kotlin 健康检查协议支持与接入方式,以运行时文档核对。
  • 就绪与存活如何区分?答:依赖未就绪摘流量,进程卡死才重启,见部署探针题目。

06.8.5.1-049 重试与退避策略如何配置?

一句话结论

仅对可重试错误(不可用、超时、连接失败)有限重试,指数退避加抖动;非幂等写操作谨慎重试;重试总次数与退避上限受控,配合熔断避免放大下游故障;重试策略在客户端层统一配置。

概念解释

重试前提:错误可重试 + 操作幂等。退避避免故障期同步冲击。可重试状态码明确清单,4xx 类业务错误不重试。重试次数受 deadline 总预算约束。重试与熔断、降级配合使用。

原理流程

  1. 调用失败判定错误码与幂等性。
  2. 可重试:退避后重试,次数递增。
  3. 超过次数抛出最后异常。
  4. 熔断打开时不再重试直接降级。

代码或图示

可重试:UNAVAILABLE / DEADLINE_EXCEEDED / 连接失败
不重试:INVALID_ARGUMENT / NOT_FOUND / 权限错误
退避:指数间隔 + 抖动 + 上限

常见误区

  • 对非幂等写操作自动重试:重复执行副作用。
  • 重试无退避:下游故障时压力叠加。

追问

  • 待确认:gRPC-Kotlin 客户端是否内置重试策略,以运行时文档核对;否则在客户端封装层实现。
  • 重试与超时关系?答:每次重试受总 deadline 约束,不无限延长。

06.8.5.1-050 可观测性:指标、日志与追踪如何落地?

一句话结论

客户端/服务端拦截器采集调用指标(次数、延迟、状态码)、结构化日志与 trace 标识;元数据透传 trace 贯穿多跳;指标按方法与状态码维度聚合,异常日志带调用上下文与 trace。

概念解释

观测三件套:指标看趋势,日志查细节,追踪串联调用链。拦截器统一埋点,业务代码不重复采集。敏感元数据脱敏。方法名、状态码、延迟分位是核心维度。慢调用与错误率告警。

原理流程

  1. 拦截器注入/读取 trace 元数据。
  2. 记录调用开始结束与状态。
  3. 上报指标维度(方法/码/延迟)。
  4. 日志按 trace 关联两侧记录。

代码或图示

指标:QPS / 延迟分位 / 状态码分布
日志:方法 / 主体 / trace-id / 错误原因
追踪:多跳调用链透传

常见误区

  • 业务方法内零散打日志:格式与维度不统一。
  • 日志记录令牌与请求体敏感字段:泄露风险。

追问

  • 待确认:gRPC-Kotlin 可观测性插件/指标暴露方式,以运行时与生态文档核对。
  • 多跳调用 trace 如何延续?答:元数据透传 trace 标识,各跳日志关联。

06.8.5.1-051 灰度发布与版本兼容部署如何配合?

一句话结论

gRPC 契约兼容保证滚动期间新旧版本互通;灰度按实例比例引流,观测错误率与延迟;客户端负载均衡识别新版本实例;破坏性变更通过新方法/新服务版本过渡,不原地改旧契约。

概念解释

滚动发布依赖向后兼容:旧客户端可调新服务端,反之亦然。灰度期间双版本实例共存,流量按策略切回。客户端 LB 剔除不健康新版本实例。废弃方法在确认无调用后下线。

原理流程

  1. 契约变更评审兼容级别。
  2. 灰度实例上线接少量流量。
  3. 观测指标无异常后全量。
  4. 旧版本实例下线,废弃契约后续清理。

代码或图示

兼容变更 -> 灰度 -> 观测 -> 全量 -> 旧版下线
破坏变更 -> 新方法/新版本 -> 双跑过渡

常见误区

  • 不兼容变更直接滚动:新旧实例调用断裂。
  • 灰度不看状态码分布:错误被平均指标掩盖。

追问

  • 待确认:项目灰度发布与服务发现流量策略,按部署文档核对。
  • 客户端如何识别新版本?答:按服务注册元数据与 LB 规则,发现机制按项目组件核对。

06.8.5.1-052 gRPC-Kotlin 运行时依赖有哪些待核对点?

一句话结论

核对:运行时库坐标与版本、protoc 与生成插件版本、Kotlin 基线、Netty/OkHttp 等传输实现依赖、健康检查与观测组件;不确定坐标与版本标待确认,以官方仓库示例为准,不编造版本号。

概念解释

依赖层次:生成插件(构建期)、运行时 Stub/基类库、传输层实现。版本矩阵需互相匹配。项目内统一版本管理,引入传递依赖时复核。离线构建需确认镜像内工具链齐全。

原理流程

  1. 查官方示例确认依赖清单。
  2. 对齐 Kotlin 与运行时版本。
  3. 核对传输实现与可选组件。
  4. 构建环境验证生成与运行。

代码或图示

核对清单:运行时坐标 / 生成插件 / 传输实现 / 健康与观测 / Kotlin 基线

常见误区

  • 只引运行时不引生成插件:编译期无产物。
  • 传递依赖版本冲突:Stub 接口与运行时不匹配。

追问

  • 待确认:gRPC-Kotlin 官方仓库的依赖坐标与版本兼容矩阵,以仓库文档为准。
  • 轻量传输实现选型?答:按部署环境与依赖体积评估,能力以运行时文档核对。

06.8.5.1-053 GraphQL-Kotlin 的定位与组成是什么?

一句话结论

graphql-kotlin 是 Kotlin 下的 GraphQL 实现:从 Kotlin 代码(查询/变更解析器、类型)生成可执行 Schema,提供 DataFetcher、DataLoader、订阅与 Federation 支持;服务端按 GraphQL 查询语法解析并按需取字段。

概念解释

组成:Schema 生成器、执行引擎、解析器契约、数据加载与扩展模块。通用 GraphQL 查询语言规范只作铺垫,本节聚焦 Kotlin 侧代码如何映射为 Schema、如何解决 N+1 与鉴权。引擎底层基于 graphql-java(按版本核对)。

原理流程

  1. 定义 Kotlin 查询/变更解析器与类型。
  2. 生成器产出可执行 Schema。
  3. 请求解析为字段执行树。
  4. DataFetcher 按字段取数,DataLoader 批量优化。

代码或图示

Kotlin 解析器/类型 -> Schema 生成 -> 查询执行树 -> DataFetcher/DataLoader

常见误区

  • 把 GraphQL 当数据库查询层:取数逻辑仍在服务端解析器。
  • 假设前端可取任意字段无限制:需要复杂度与权限控制。

追问

  • 待确认:graphql-kotlin 模块拆分(schema-generator / federation / subscriptions)与底层引擎版本,以官方文档核对。
  • 与 REST 共存吗?答:可同进程分路由提供,按接口形态选型。

06.8.5.1-054 Schema 如何从代码生成?

一句话结论

Schema 生成器扫描查询/变更/订阅解析器与其返回类型,把 Kotlin 函数与属性映射为 GraphQL 字段与类型;函数参数映射为查询参数;生成可执行 Schema 后交给引擎执行。

概念解释

代码优先(code-first):Kotlin 代码是 Schema 事实来源,SDL 由生成产出。解析器函数签名决定字段类型与参数。类型可空性、返回类型、参数类型直接映射 GraphQL 类型系统。配置决定命名与可见性。

原理流程

  1. 定义 Query/Mutation 解析器类与函数。
  2. 生成器反射读取签名与返回类型。
  3. 映射字段、参数与类型。
  4. 生成可执行 Schema 注册到服务端。

代码或图示

class QueryService {
    fun getUser(id: String): UserDto? = /* ... */
}

常见误区

  • 解析器返回类型与 DTO 类型不匹配:Schema 生成报错或类型异常。
  • 手写 SDL 与代码不一致:双来源漂移。

追问

  • 待确认:生成器扫描配置(包/类/属性)与注解,以 graphql-kotlin 文档核对。
  • 字段命名如何映射?答:按配置的驼峰/字段名策略,默认规则以文档核对。

06.8.5.1-055 Query、Mutation、Subscription 解析器分别是什么?

一句话结论

Query 处理只读查询,Mutation 处理写操作并返回变更结果,Subscription 通过事件流推送实时数据;三者是 Schema 的根操作类型,各自解析器函数注册到对应根节点。

概念解释

职责划分对应操作语义:Query 幂等只读,Mutation 有副作用,Subscription 建立持续推送通道。解析器都是 Kotlin 函数,Subscription 额外返回流类型。根解析器组织子域字段,可分层组合。

原理流程

  1. Query 解析器注册只读字段。
  2. Mutation 解析器处理写入并返回结果。
  3. Subscription 解析器返回事件流。
  4. 请求按操作类型进入对应根节点执行。

代码或图示

class Query { fun user(id: String): UserDto? = ... }
class Mutation { fun createUser(name: String): UserDto = ... }
class Subscription { fun orderUpdates(): Flow<OrderDto> = ... }

常见误区

  • 在 Query 解析器写副作用:语义不符且被缓存/预取误伤。
  • Subscription 实现成普通查询:没有持续推送能力。

追问

  • 待确认:Subscription 流类型(Flow/ Publisher)在 graphql-kotlin 中的支持形式,以文档核对。
  • 根解析器如何拆分多域?答:按领域组合多个 resolver,生成器聚合到根节点。

06.8.5.1-056 DataFetcher 的角色是什么?

一句话结论

DataFetcher 是字段取数逻辑:引擎执行到某字段时调用对应 Fetcher 从父对象或数据源取值;Kotlin 解析器函数在生成时被适配为 DataFetcher;字段级取数隔离,父对象与子字段分别取数。

概念解释

执行树中每个字段有独立 Fetcher:顶层字段调用根解析器,嵌套字段从父对象取属性或再查数据源。Fetcher 能拿到父对象、参数与上下文。N+1 优化在 Fetcher 层通过 DataLoader 批量解决。

原理流程

  1. 引擎定位字段执行节点。
  2. 调用该字段 DataFetcher。
  3. Fetcher 读取父对象/参数/上下文取数。
  4. 结果交给类型完成与子字段执行。

代码或图示

字段执行 -> DataFetcher(父对象 + 参数 + 上下文)-> 返回字段值

常见误区

  • 每个嵌套字段 Fetcher 单独查库:N+1 问题产生。
  • Fetcher 内持有请求外可变状态:并发串数据。

追问

  • 待确认:graphql-kotlin 中自定义 DataFetcher 注册方式,以文档核对。
  • Fetcher 能访问当前请求主体吗?答:经上下文传递,见鉴权题目。

06.8.5.1-057 GraphQL 类型系统如何映射 Kotlin 类型?

一句话结论

对象类型对应 Kotlin 类/数据类,标量对应基础类型,枚举对应 Kotlin enum,接口/联合对应继承或密封类型;可空性直接映射 GraphQL 可空/非空;字段与属性按映射规则生成。

概念解释

类型映射保持类型安全:Kotlin 空安全体现为 GraphQL 非空约束。接口/联合在 Kotlin 侧用继承层次或 sealed class 表达。标量默认类型与自定义标量补充。列表映射为集合类型。

原理流程

  1. Kotlin 类 -> 对象类型。
  2. 可空性 -> GraphQL 可空标记。
  3. enum/接口/密封类 -> 对应类型。
  4. 集合 -> 列表类型。

代码或图示

Kotlin class -> GraphQL type
Kotlin T? -> 可空;T -> 非空
enum class -> enum
sealed class -> 联合/接口
List<T> -> [T]

常见误区

  • 返回可空却声明非空:执行期类型错误。
  • 联合类型未建模层次:生成 Schema 失败。

追问

  • 待确认:接口与联合在 graphql-kotlin 中的注解/类型映射方式,以文档核对。
  • 自定义复杂类型嵌套怎么生成?答:递归引用返回类型,生成器沿类型图展开。

06.8.5.1-058 空安全如何映射到 GraphQL?

一句话结论

Kotlin 类型非空(T)映射 GraphQL 非空,可空(T?)映射可空;Fetcher 返回 null 与非空声明冲突时执行期报错;字段参数可空性同样映射;Schema 生成时校验空安全一致性。

概念解释

空安全是 Kotlin 与 GraphQL 类型系统的契合点。非空字段 Fetcher 不得返回 null;嵌套可空对象内部字段按自身声明处理。执行错误按字段位置上报,不影响其他已取数字段。

原理流程

  1. 生成器读取 Kotlin 可空性。
  2. 映射 GraphQL 可空标记。
  3. 执行时 Fetcher 结果校验空约束。
  4. 冲突上报字段错误。

代码或图示

fun getUser(id: String): UserDto? // 可空字段
fun name(): String                // 非空字段

常见误区

  • Kotlin 侧平台类型未标注空性:映射结果不确定。
  • 非空 Fetcher 可能返回 null:执行期错误。

追问

  • 待确认:生成器对平台类型(Java 互操作)的可空推断规则,以文档核对。
  • 嵌套对象为 null 时子字段怎么处理?答:父字段为 null 则子字段不再执行,按 GraphQL 规则。

06.8.5.1-059 依赖图与字段执行树是什么结构?

一句话结论

查询文本解析为包含所选字段与参数的执行树,节点按对象类型组织父子关系;引擎自上而下执行:先取父字段值,再对父结果执行子字段;字段间依赖通过父对象传递,兄弟字段可并行取数。

概念解释

执行树是查询的结构化表示:根操作 -> 对象字段 -> 嵌套字段。引擎调度各节点 Fetcher。兄弟字段无依赖时可并发执行;嵌套字段基于父结果。树深度与宽度决定查询成本,是复杂度控制的对象。

原理流程

  1. 查询解析与校验形成执行树。
  2. 根节点调用根 Fetcher。
  3. 父结果就绪后执行子字段。
  4. 兄弟字段按引擎调度并行。

代码或图示

Query
├─ user(id) -> User
│   ├─ name
│   └─ orders -> [Order]
│       └─ item

常见误区

  • 把嵌套字段当独立请求理解:执行基于父对象逐级展开。
  • 不控制树深度:恶意深查询拖垮服务。

追问

  • 待确认:graphql-java 引擎并发执行策略,以底层引擎文档核对。
  • 字段批量优化在哪一层?答:子字段取数经 DataLoader 合并,见后续题目。

06.8.5.1-060 一个 GraphQL 请求的执行流程是什么?

一句话结论

流程:解析查询文本 -> 校验 Schema 与语法 -> 形成执行树 -> 按节点调度 Fetcher 取数 -> 组装响应;字段错误独立上报,不必然中断整个响应;查询可被缓存与复杂度分析前置处理。

概念解释

执行分阶段:解析、校验、计划、执行、结果组装。校验拒绝语法错误与未知字段。执行阶段按树调度。响应结构与查询选择字段一致。错误按字段位置返回,部分成功是 GraphQL 常见形态。

原理流程

  1. 解析操作与字段选择。
  2. 校验类型、参数与权限前置规则。
  3. 生成执行计划。
  4. 调度 Fetcher 取数并组装响应。

代码或图示

解析 -> 校验 -> 执行树 -> Fetcher 调度 -> 结果组装(字段级错误)

常见误区

  • 期待所有错误整体失败:GraphQL 字段级部分成功。
  • 不做查询校验:非法字段与深查询进入执行层。

追问

  • 待确认:graphql-kotlin 请求入口与执行阶段钩子,以官方文档核对。
  • 预检(persisted query)在哪一步?答:解析前匹配预注册查询,见后续题目。

06.8.5.1-061 Schema 生成依赖反射还是编译期处理?

一句话结论

graphql-kotlin 代码优先方案在运行时通过反射读取解析器签名与类型信息生成 Schema;编译期不生成独立 GraphQL 代码;类型映射依赖 Kotlin 反射元数据,需保留反射所需信息(无参构造、属性可见性等)。

概念解释

运行时反射方案的约束:类与属性可被反射访问,避免混淆裁剪元数据。Schema 生成在应用启动期完成,运行期执行走引擎。反射开销在启动阶段,不在每次请求。具体生成机制以官方版本文档核对。

原理流程

  1. 启动期生成器反射扫描解析器。
  2. 读取签名、返回类型与参数。
  3. 构建 Schema 类型图。
  4. 请求执行走引擎 Fetcher 调用。

代码或图示

启动期:反射生成 Schema
请求期:引擎执行 Fetcher(无 Schema 反射)

常见误区

  • 混淆/裁剪导致反射元数据丢失:Schema 生成缺字段。
  • 每次请求重新生成 Schema:启动开销被重复放大。

追问

  • 待确认:graphql-kotlin 是否提供编译期代码生成选项,以官方文档核对。
  • 反射性能影响在哪?答:仅启动生成阶段,运行期取数不重复反射整个类型图。

06.8.5.1-062 自定义标量如何注册?

一句话结论

默认标量覆盖基础类型,特殊类型(日期、金额、ID、JSON 原始串)通过自定义标量注册:配置序列化/反序列化与 GraphQL 类型名;Kotlin 类型与标量双向映射,非法值在校验层拒绝。

概念解释

自定义标量补充类型系统表达:如 Instant、Decimal、UUID。注册包含类型名、运行时类名与编解码逻辑。前端按标量格式交互,服务端映射 Kotlin 类型。标量校验非法输入返回字段错误。

原理流程

  1. 定义 Kotlin 目标类型。
  2. 注册标量名与编解码函数。
  3. 解析器返回/接收该类型。
  4. 执行时按标量转换校验。

代码或图示

// 示意:自定义标量注册(API 以官方文档为准)
// 日期/金额/UUID -> 自定义 Scalar

常见误区

  • 用 String 表达所有特殊类型:丢失类型校验与前端契约。
  • 标量编解码不校验格式:非法值流入业务。

追问

  • 待确认:graphql-kotlin 自定义标量注册 API 与内置标量清单,以文档核对。
  • 金额用什么标量?答:高精度十进制表达,不用浮点,按项目约定格式。

06.8.5.1-063 输入类型与参数校验如何做?

一句话结论

Mutation/Query 参数映射为 GraphQL 输入类型;参数校验(必填、范围、格式、业务规则)在解析器前置层或公共校验器完成,非法输入返回字段级错误;输入 DTO 与输出 DTO 分离。

概念解释

输入类型是请求侧数据结构,区别于输出对象类型。校验分层:类型与非空由 Schema 保证,格式与业务规则由应用层校验。多条字段错误可汇总返回。校验规则在解析器或独立校验组件复用。

原理流程

  1. 定义输入 DTO 类型。
  2. Schema 映射参数与非空约束。
  3. 解析器前置校验输入。
  4. 非法输入汇总字段错误返回。

代码或图示

data class CreateUserInput(val name: String, val age: Int?)
fun createUser(input: CreateUserInput): UserDto

常见误区

  • 输入类型直接复用领域实体:内部结构外泄。
  • 校验散落在各 Mutation:规则不一致。

追问

  • 待确认:graphql-kotlin 是否集成校验注解/组件,以生态文档核对;否则公共校验函数实现。
  • 嵌套输入怎么校验?答:递归校验输入树,错误定位到字段路径。

06.8.5.1-064 错误处理与 null 字段如何返回?

一句话结论

字段级错误放入响应 errors 数组并标注字段路径,对应字段数据为 null;部分字段失败不影响其他字段返回;未预期异常兜底记录日志并返回中性错误,不泄露堆栈;错误分类按业务码与状态区分。

概念解释

GraphQL 响应含 data 与 errors 两部分。每个错误定位到路径。业务校验错误、权限错误、系统错误分类处理。日志记录完整堆栈与 trace,响应消息中性。字段 null 与执行错误要区分表达。

原理流程

  1. Fetcher 执行抛出/返回错误。
  2. 引擎收集错误并关联字段路径。
  3. 成功字段组装 data,失败字段为 null。
  4. 兜底异常记录日志,返回中性错误结构。

代码或图示

{
  "data": { "user": null },
  "errors": [{ "path": ["user"], "message": "not found" }]
}

常见误区

  • 一个字段失败清空整个 data:违背字段级部分成功语义。
  • 响应回显堆栈与内部类名:信息泄露。

追问

  • 待确认:graphql-kotlin 错误捕获与异常到字段错误的映射配置,以文档核对。
  • 权限错误放 errors 还是 data null?答:按 API 约定,错误码在 errors 表达,字段为 null。

06.8.5.1-065 graphql-kotlin 依赖坐标有哪些待核对点?

一句话结论

核对:Schema 生成器模块坐标、Federation/Subscription 可选模块、底层 graphql-java 版本、Kotlin 基线兼容;不确定坐标与版本标待确认,以官方仓库与依赖仓库为准,不编造版本号。

概念解释

模块按需引入:基础生成器、联邦、订阅、序列化适配。版本矩阵互相匹配。项目内统一版本管理。可选模块(如 federation)按是否使用微服务网关架构引入。

原理流程

  1. 查官方仓库确认模块清单与坐标。
  2. 对齐 Kotlin 与底层引擎版本。
  3. 按需引入订阅/联邦模块。
  4. 启动生成 Schema 验证依赖齐全。

代码或图示

核对清单:生成器模块 / federation / subscriptions / 底层引擎版本 / Kotlin 基线

常见误区

  • 只引核心模块漏订阅模块:订阅功能不可用。
  • 底层引擎与生成器版本不匹配:执行期行为异常。

追问

  • 待确认:graphql-kotlin 官方仓库最新稳定坐标与版本兼容说明,以仓库文档为准。
  • 版本升级先验证什么?答:Schema 生成、查询执行、订阅与批量加载回归。

06.8.5.1-066 Schema 导出 SDL 与前端如何协作?

一句话结论

生成 Schema 后可导出 SDL(GraphQL 定义语言)作为前后端契约;前端基于 SDL 生成类型与查询;代码优先方案以 Kotlin 代码为准生成 SDL,契约变更走版本与评审;SDL 不手工编辑与代码对抗。

概念解释

SDL 是可阅读的契约快照,供前端工具链生成类型与文档。代码优先:代码变更 -> 重新导出 SDL -> 前端同步。变更评审检查破坏性字段删除/类型修改。契约兼容规则与 API 版本策略配套。

原理流程

  1. 启动/构建期从代码生成 Schema。
  2. 导出 SDL 文件供前端工具使用。
  3. 前端按 SDL 生成类型与操作。
  4. 契约变更走版本过渡。

代码或图示

Kotlin 代码 -> Schema -> 导出 SDL -> 前端类型生成 / 文档

常见误区

  • 手工改 SDL 不改代码:下次导出被覆盖。
  • 破坏性变更不通知前端:查询断裂。

追问

  • 待确认:graphql-kotlin SDL 导出 API 与任务方式,以官方文档核对。
  • 契约变更怎么管理?答:字段废弃过渡、版本标识,按项目 API 流程核对。

06.8.5.1-067 GraphQL 中的 N+1 问题如何产生?

一句话结论

取 N 个父对象后,每个父对象的嵌套字段各自单独查一次数据源,产生 1 次父查询 + N 次子查询;嵌套列表与关联字段越多越明显;根源是字段 Fetcher 之间互不知道彼此在批量取数。

概念解释

典型场景:查 100 个用户,每个用户的订单字段各自调一次订单查询,共 101 次查询。关系型数据库表现为连接数与往返放大。N+1 是 GraphQL 嵌套模型的经典问题,必须在取数层批量优化,不能靠数据库索引掩盖。

原理流程

  1. 父字段 Fetcher 取 N 个父对象。
  2. 每个父对象子字段 Fetcher 独立查询关联数据。
  3. 产生 N 次重复关联查询。
  4. 批量加载合并为一次查询消除 N 次往返。

代码或图示

1 次查用户列表 -> 每个用户各查一次订单 = 1 + N 次查询

常见误区

  • 嵌套字段每次单独查库:N+1 随列表规模放大。
  • 用懒加载在对象内部查询: Fetcher 仍逐字段触发。

追问

  • 哪些字段容易触发?答:一对多关联、嵌套引用、列表内子对象字段。
  • 待确认:项目中 ORM 懒加载与 GraphQL 取数的叠加情况,按数据访问层核对。

06.8.5.1-068 DataLoader 原理与批量加载如何工作?

一句话结论

DataLoader 按 key 收集同一批次内的加载请求,批量函数一次取出所有 key 对应数据并按 key 回填;请求在微任务/批次窗口内合并,消除逐对象查询;同一 key 自动去重缓存。

概念解释

DataLoader 分三步:收集 key -> 调用批量加载函数 -> 按 key 映射结果回填。批量函数接收 key 集合返回 key->值 映射。批次窗口由引擎调度控制。去重保证同一 key 一次加载。这是 GraphQL 生态解决 N+1 的标准机制。

原理流程

  1. 子字段 Fetcher 向 Loader 提交 key。
  2. Loader 收集本批次 key 并去重。
  3. 批量函数一次查询返回映射。
  4. 结果按 key 回填各字段。

代码或图示

load(key) 收集 -> batchLoad(keys): Map<key, value> -> 回填各字段

常见误区

  • 批量函数仍逐 key 查询:合并未生效。
  • Loader 跨请求复用缓存:不同请求数据串扰。

追问

  • 待确认:graphql-kotlin DataLoader 集成方式与批次调度 API,以官方文档核对。
  • 批量取不到的 key 怎么处理?答:映射中置 null 或按错误策略返回,字段为 null。

06.8.5.1-069 DataLoader 如何注册与确定作用域?

一句话结论

DataLoader 按请求作用域创建与注册:单次查询内合并批次,请求结束即丢弃;不能做成全局单例缓存跨请求数据;Loader 实例经 GraphQL 上下文传给对应 Fetcher;多类型字段各用独立 Loader。

概念解释

作用域决定缓存边界:请求级 Loader 合并本次查询的重复加载,不跨请求缓存业务数据。上下文在请求创建时初始化 Loader 集合。全局单例只会造成数据串扰与陈旧缓存。缓存策略(内存批次缓存)在 Loader 内受控开启。

原理流程

  1. 请求开始创建请求级 Loader 实例。
  2. 注册到执行上下文。
  3. Fetcher 从上下文取对应 Loader。
  4. 请求结束销毁 Loader 与批次缓存。

代码或图示

请求作用域:Loader 创建 -> 上下文注册 -> Fetcher 使用 -> 请求结束销毁

常见误区

  • Loader 设为全局单例:跨请求数据污染。
  • 上下文未注册 Loader:Fetcher 取不到实例。

追问

  • 待确认:graphql-kotlin 上下文与 Loader 注册 API,以官方文档核对。
  • 跨请求缓存另怎么做?答:独立缓存层按失效策略管理,不依赖请求级 Loader 缓存。

06.8.5.1-070 批处理函数如何设计?

一句话结论

批量函数接收 key 集合,一次性查询返回 key 到值的映射;批量查询保留顺序无关性,缺失 key 显式映射 null;函数应处理空集合、去重与批量大小上限;单次批量过大时分批查询,避免超大 IN 列表。

概念解释

批量函数是 DataLoader 与数据源之间的适配层:输入 key 集合,输出结果映射。设计要点:一次查询覆盖全部 key、处理缺失值、控制批量大小、错误隔离。批量 SQL/远程调用在函数内合并。函数保持无请求级可变状态。

原理流程

  1. 接收去重后的 key 集合。
  2. 空集合直接返回空映射。
  3. 分批查询并组装 key->值映射。
  4. 缺失 key 置 null,异常按策略处理。

代码或图示

suspend fun batchLoad(keys: List<String>): Map<String, UserDto> {
    return userRepository.findByIds(keys).associateBy { it.id }
}

常见误区

  • 批量函数内部循环逐个查:N+1 未消除。
  • 批量结果不按 key 对齐:回填错误对象。

追问

  • 批量大小上限怎么定?答:按数据源 IN 限制与报文大小分批,Loader 窗口配合。
  • 待确认:批量函数签名(挂起/集合返回)在 graphql-kotlin 中的要求,以文档核对。

06.8.5.1-071 DataLoader 的缓存与去重如何工作?

一句话结论

同一批次内相同 key 只加载一次,Loader 可开启批次内缓存避免重复提交;缓存生命周期限定在请求作用域,不跨请求保留业务数据;缓存命中直接返回,未命中进入批量函数。

概念解释

去重是合并请求的天然结果:同一 key 多个字段引用只算一次。批次缓存减少同请求内重复加载。跨请求缓存属于独立缓存层,需失效策略,不能借用 Loader 缓存。缓存键与批量函数 key 类型一致。

原理流程

  1. 提交 key 先查批次缓存。
  2. 未命中收集到待加载集合并去重。
  3. 批量函数返回后写入缓存。
  4. 请求结束缓存随 Loader 销毁。

代码或图示

key 提交 -> 缓存命中直接返回 / 未命中去重 -> 批量加载 -> 回填缓存

常见误区

  • 把 Loader 缓存当跨请求二级缓存:陈旧数据串请求。
  • 不同业务类型共用同一 Loader:key 空间冲突。

追问

  • 待确认:graphql-kotlin Loader 缓存开关与默认行为,以官方文档核对。
  • 批量结果含错误时缓存什么?答:按策略缓存失败标记或不缓存,避免错误被复用。

06.8.5.1-072 Subscription 订阅在 Kotlin 侧如何实现?

一句话结论

Subscription 解析器返回事件流(Flow 或适配的响应式流),引擎把流事件推送给订阅客户端;事件来源可以是消息队列、领域事件或轮询转换;流随订阅取消而终止,资源在结束时清理。

概念解释

订阅是持续推送通道:解析器建立事件流,引擎转发每个事件。Kotlin 协程 Flow 自然适配流语义。事件来源与取数逻辑在解析器/服务层组织。订阅生命周期与客户端连接绑定。具体流类型支持以 graphql-kotlin 版本核对。

原理流程

  1. 客户端发起订阅请求。
  2. 解析器建立事件流。
  3. 事件到达逐个推送给客户端。
  4. 取消/结束时关闭流并清理订阅。

代码或图示

class Subscription {
    fun orderUpdates(): Flow<OrderDto> = orderEventFlow
}

常见误区

  • 订阅解析器返回单次查询结果:没有持续推送。
  • 事件流不随订阅取消关闭:后台任务泄漏。

追问

  • 待确认:graphql-kotlin 订阅模块与 Flow/Publisher 适配方式,以官方文档核对。
  • 多实例事件怎么汇聚?答:经消息中间件广播到各节点订阅者,见后续题目。

06.8.5.1-073 订阅与 WebSocket/SSE 传输是什么关系?

一句话结论

GraphQL Subscription 通常依托 WebSocket 传输建立长连接推送(部分实现支持 SSE 等替代传输);传输层负责连接与消息协议,GraphQL 层定义订阅操作与事件格式;传输选择按浏览器/网络环境核对实现支持度。

概念解释

铺垫:双向长连接一般走 WS,单向推送可考虑 SSE。GraphQL 订阅协议在传输之上约定连接初始化、订阅消息与事件帧。服务端订阅模块与传输层配合,连接鉴权在握手阶段完成。

原理流程

  1. 客户端经长连接建立 GraphQL 会话。
  2. 发起订阅操作。
  3. 事件流经传输层推送。
  4. 取消订阅或断连终止通道。

代码或图示

传输:WebSocket(常见)/ SSE(单向替代)
协议:GraphQL 订阅消息帧 + 事件载荷

常见误区

  • 以为 Subscription 走普通 HTTP 短连接:无法持续推送。
  • 传输鉴权与订阅授权脱节:握手通过后不校验订阅权限。

追问

  • 待确认:graphql-kotlin 当前支持的传输协议与协议子版本,以官方文档核对。
  • 多节点订阅事件如何送达?答:节点订阅中间件主题,本地匹配订阅者推送。

06.8.5.1-074 Federation 是什么概念,实体如何扩展?

一句话结论

Federation 把多个 GraphQL 子图组成一个联合网关:各子图暴露自身类型,网关通过实体标识(key)跨子图扩展字段;类型由拥有方定义,其他子图可向实体补充字段,客户端对网关查询统一数据。

概念解释

铺垫:联邦是 GraphQL 微服务化方案。实体用 key 标识可跨服务引用;子图声明可扩展实体与 resolver。网关编排各子图字段。Kotlin 侧通过 federation 模块注解/配置声明实体扩展。本节聚焦 Kotlin 落地,不展开联邦协议细节。

原理流程

  1. 子图声明实体 key 与扩展字段。
  2. 网关聚合子图 Schema。
  3. 查询命中跨子图字段时按实体 key 取数。
  4. 各子图 resolver 返回扩展数据。

代码或图示

子图 A:拥有 User 基础字段
子图 B:按 User key 扩展 orders 字段
网关:聚合为统一 Schema

常见误区

  • 各子图重复定义同一实体字段:归属冲突。
  • 实体 key 不稳定:跨子图引用失败。

追问

  • 待确认:graphql-kotlin federation 模块版本与实体注解方式,以官方文档核对。
  • 联邦适合多大规模?答:按团队拆分边界评估,单体服务不必引入联邦复杂度。

06.8.5.1-075 Federation 实体解析器(entity resolver)如何工作?

一句话结论

实体解析器按实体 key 从本子图加载被扩展的实体对象;网关请求跨子图字段时,携带 key 调用对应实体 resolver;resolver 返回本子图拥有的扩展字段数据,与拥有方字段合并。

概念解释

实体 resolver 是跨服务取数入口:输入是实体标识,输出是本子图视角的实体。它与普通字段 Fetcher 配合:基础字段来自拥有方,扩展字段来自联邦子图。key 解析与加载失败返回字段错误。

原理流程

  1. 网关识别字段归属子图。
  2. 携带实体 key 调用子图实体 resolver。
  3. resolver 按 key 加载数据。
  4. 返回扩展字段,网关合并结果。

代码或图示

// 示意:按 key 解析实体(注解/签名以 federation 模块为准)
fun findUserByKey(id: String): UserDto?

常见误区

  • 实体 resolver 加载完整实体却只补一个字段:取数成本浪费。
  • key 格式两侧不一致:跨服务解析失败。

追问

  • 待确认:实体 resolver 注册方式与 key 表示形式,以 graphql-kotlin federation 文档核对。
  • 实体不存在怎么返回?答:按联邦约定返回 null 或字段错误,避免网关整体失败。

06.8.5.1-076 跨服务字段扩展如何避免归属冲突?

一句话结论

字段归属明确:基础类型与字段由拥有方子图定义,扩展方只追加自身字段;字段命名与类型在契约评审中对齐;避免两个子图扩展同名字段;实体 key 与版本约定跨服务一致。

概念解释

联邦治理核心是归属边界。冲突表现:同名字段类型不一致、重复扩展、key 语义分歧。契约评审与 SDL 对比发现冲突。扩展方不修改拥有方字段语义。接口版本演进按兼容规则过渡。

原理流程

  1. 定义实体拥有方与扩展方。
  2. 扩展字段命名与类型评审对齐。
  3. 网关聚合时校验字段归属。
  4. 变更走跨服务契约评审。

代码或图示

归属规则:拥有方定义基础字段 / 扩展方追加独立字段 / 命名唯一不冲突

常见误区

  • 多个子图扩展同名字段:网关解析歧义。
  • 扩展方依赖拥有方内部字段结构:耦合过深。

追问

  • 待确认:联邦聚合时字段冲突检测行为,以网关实现核对。
  • 契约变更跨服务怎么协调?答:版本过渡 + 废弃字段流程,按项目治理约定。

06.8.5.1-077 网关编排与子图如何配合?

一句话结论

网关(Federation gateway)聚合子图 Schema,按查询字段归属分发到对应子图,合并各子图返回结果;子图独立部署与扩展;网关负责编排、跨子图取数与协议入口,业务数据逻辑留在子图。

概念解释

编排层不实现业务取数,只做字段路由与结果合并。子图暴露独立可调用的 GraphQL 服务。网关处理查询计划:哪些字段去哪个子图、实体 key 如何传递。子图间不直接互相依赖取数字段。

原理流程

  1. 网关聚合各子图 Schema。
  2. 解析查询生成执行计划。
  3. 按字段归属并行/串行调用子图。
  4. 合并结果返回客户端。

代码或图示

客户端 -> 网关(聚合 + 编排)-> 子图 A / 子图 B(各自取数)

常见误区

  • 网关写业务聚合逻辑:编排层变胖,子图复用性下降。
  • 子图之间直接调用补字段:绕过联邦编排。

追问

  • 待确认:项目是否采用联邦网关,按架构文档核对;单体 GraphQL 服务无此层。
  • 网关性能瓶颈在哪?答:查询计划编排与跨子图往返,观测各子图耗时。

06.8.5.1-078 订阅消息的背压如何处理?

一句话结论

订阅事件流按客户端消费速率推送,慢消费通过有界缓冲与背压控制;溢出按策略丢弃非关键事件或通知降级;订阅者集合与事件生产解耦,避免单个慢订阅者拖垮事件源。

概念解释

订阅背压与普通流式调用一致:生产速率可能高于消费速率。缓冲队列有界,事件分级处理。慢订阅者隔离:不阻塞全局事件源。连接断开后清理订阅与缓冲。事件顺序在单订阅者内保持。

原理流程

  1. 事件源生产事件。
  2. 按订阅者入有界队列。
  3. 队列满执行丢弃/阻塞策略。
  4. 断连清理队列与订阅。

代码或图示

事件源 -> 各订阅者有界队列 -> 推送通道
满队列:分级丢弃 / 降级通知

常见误区

  • 无界队列缓存事件:慢连接拖垮内存。
  • 单个慢订阅者阻塞全局广播:影响其他订阅者。

追问

  • 待确认:graphql-kotlin 订阅流的背压与缓冲配置,以模块文档核对。
  • 关键事件能丢吗?答:按业务分级,关键事件需持久化或重放机制。

06.8.5.1-079 鉴权在 GraphQL 解析层如何做?

一句话结论

认证在请求入口完成(HTTP/传输层),主体放入执行上下文;授权在字段 Fetcher 或联邦解析层按字段与数据归属判定;未授权字段返回字段级错误,不暴露无权限数据。

概念解释

GraphQL 鉴权分两层:入口认证识别主体,字段级授权控制可见性。主体经上下文传给所有 Fetcher。权限判断可按类型/字段配置,也可在 Fetcher 内做数据归属校验。区别于 REST 按路由鉴权,GraphQL 是单入口多字段。

原理流程

  1. 请求入口认证,主体写入上下文。
  2. 执行计划与 Fetcher 读取主体。
  3. 字段级权限判定。
  4. 无权限字段错误或隐藏,不返回数据。

代码或图示

入口认证 -> 主体入上下文 -> Fetcher 字段授权 + 数据归属校验

常见误区

  • 只在入口认证不做字段授权:单入口下所有字段同一权限面。
  • 无权限字段返回 null 却泄露存在性:按约定处理提示。

追问

  • 待确认:graphql-kotlin 鉴权注解/扩展支持,以官方文档核对。
  • 联邦子图如何鉴权?答:主体随请求上下文传递到子图,子图独立校验。

06.8.5.1-080 认证主体如何传到 DataFetcher?

一句话结论

主体在请求创建时放入 GraphQL 执行上下文,Fetcher 从上下文读取;上下文按请求隔离,不存全局可变状态;解析器函数签名或上下文参数获取主体,传给服务层做授权与数据过滤。

概念解释

上下文是请求级通道:主体、Loader、服务依赖都经上下文传递。Fetcher 访问上下文对象,避免依赖全局 ThreadLocal。每个请求上下文独立,并发不串扰。主体不可变,请求结束随上下文销毁。

原理流程

  1. 入口认证构造主体。
  2. 请求上下文初始化写入主体与 Loader。
  3. Fetcher 从上下文取主体。
  4. 服务层按主体过滤数据。

代码或图示

// 示意:Fetcher 经上下文取主体(API 以模块文档为准)
val principal = context.principal

常见误区

  • 主体存全局变量:并发请求串号。
  • Fetcher 重新解析令牌:绕过入口认证结果。

追问

  • 待确认:graphql-kotlin 上下文访问 API 与扩展方式,以官方文档核对。
  • 依赖注入到 Fetcher 怎么做?答:上下文装配或构造器注入服务,按项目 DI 组织。

06.8.5.1-081 字段级权限控制如何实现?

一句话结论

按字段或类型配置允许的角色/权限,执行前或 Fetcher 内判定;无权限字段返回错误或从结果隐藏;数据归属权限在取数时按主体过滤;权限规则集中维护,不在各 Fetcher 散落硬编码。

概念解释

字段级控制解决单入口多权限问题:不同角色可见不同字段。实现方式:声明式权限注解/规则,或 Fetcher 内显式判定。敏感字段(联系方式、财务数据)单独授权。规则可测试、可枚举审计。

原理流程

  1. 定义字段权限规则。
  2. 执行计划/Fetcher 读取主体角色。
  3. 无权限字段拦截或返回错误。
  4. 数据归属在查询条件层过滤。

代码或图示

字段规则:角色/权限 -> 可见 / 隐藏 / 错误
数据归属:查询条件带主体与租户约束

常见误区

  • 权限判断只按 Query 层级:嵌套字段未单独控制。
  • 无权限字段仍返回空对象:泄露字段存在性。

追问

  • 待确认:是否有现成字段权限扩展,以 graphql-kotlin 生态文档核对。
  • 权限变更如何生效?答:主体刷新或请求内读取最新角色,按会话策略核对。

06.8.5.1-082 查询复杂度如何限制?

一句话结论

为字段/类型配置权重,按查询选择的字段累计复杂度;超过阈值拒绝执行;列表分页字段附加乘子权重;复杂度限制防止客户端请求超大结果集拖垮服务,与深度限制配合。

概念解释

复杂度按字段成本估算:标量字段低权重,关联列表与重查询字段高权重。阈值在请求执行前计算,超限直接拒绝。权重配置在 Schema 层,避免每个 Fetcher 自行判断。复杂度模型可覆盖列表基数乘子。

原理流程

  1. 为字段配置复杂度权重。
  2. 查询解析后累计总复杂度。
  3. 超阈值拒绝并返回错误。
  4. 未超限进入执行。

代码或图示

复杂度 = Σ 字段权重 × 列表基数乘子
超限 -> 拒绝执行(不进入 Fetcher)

常见误区

  • 只限制查询深度不限制宽度:宽查询取大量字段同样昂贵。
  • 重查询字段权重与普通字段相同:成本估算失真。

追问

  • 待确认:graphql-kotlin/底层引擎复杂度分析配置入口,以文档核对。
  • 复杂度阈值按什么定?答:按压测单请求成本与服务容量设定,分级阈值。

06.8.5.1-083 查询深度与循环片段如何防护?

一句话结论

限制嵌套最大深度,防止递归片段与深嵌套查询;检测循环引用片段;深度在解析/校验阶段计算,超限拒绝;类型循环引用在 Schema 设计上保证可终止,查询层防护兜底恶意嵌套。

概念解释

深度防护针对恶意或误写的深嵌套片段。GraphQL 片段可组合叠加,深度失控放大执行树。深度限制与复杂度、列表上限配合。Schema 类型自引用(如树节点)是合法设计,查询层仍需限深。

原理流程

  1. 解析查询计算嵌套深度。
  2. 超过最大深度拒绝。
  3. 校验片段引用合法性。
  4. 合法自引用类型在业务层控制展开深度。

代码或图示

防护:最大深度限制 + 片段循环检测 + 列表分页上限

常见误区

  • 只防深度不防宽度:宽列表查询耗尽内存。
  • 自引用类型不限深:树节点递归展开失控。

追问

  • 待确认:底层引擎深度限制配置方式,以 graphql-java 文档核对。
  • 树结构查询怎么控制展开?答:参数限制层级,Fetcher 按深度截断。

06.8.5.1-084 限流与持久化查询(Persisted Query)如何配合?

一句话结论

限流按主体/接口维度控制查询频率;持久化查询把常见操作预注册为查询 ID,客户端提交 ID 而非全文,降低解析成本并限制可执行查询集合;两者分别保护流量与查询白名单。

概念解释

限流防单主体打爆服务;持久化查询收敛服务端可接受的查询形态,防止任意复杂查询进入执行。预注册查询在构建/发布阶段登记,生产环境只放行已注册操作。未注册查询可拒绝或仅内网允许全文。

原理流程

  1. 按主体/接口配置限流配额。
  2. 发布阶段注册常用查询 ID 与文档。
  3. 客户端提交查询 ID 与变量。
  4. 未注册/超限请求拒绝。

代码或图示

限流:频率/并发配额
持久化查询:预注册操作 ID -> 白名单执行

常见误区

  • 公网开放任意全文查询:复杂查询无白名单约束。
  • 持久化查询不随版本更新注册:新操作不可用。

追问

  • 待确认:graphql-kotlin 是否内置 persisted query 支持,以生态文档核对;否则在入口层实现。
  • 限流维度选什么?答:匿名按 IP,登录按用户/租户,与 REST 限流策略一致。

06.8.5.1-085 查询变量(variables)如何传递与校验?

一句话结论

查询文本声明变量,客户端在独立 variables 对象传值;引擎按变量类型校验非空与类型;变量值在 Fetcher 经参数引用;校验错误定位到变量路径,非法值不进入业务取数。

概念解释

变量分离查询文本与参数值,便于复用与安全传参。类型在 Schema 参数声明,校验由引擎完成基础类型与非空,业务规则在解析器前置校验。变量不拼进查询文本,避免注入式构造。

原理流程

  1. 查询声明变量类型。
  2. 客户端提交 variables 对象。
  3. 引擎校验类型与非空。
  4. Fetcher 读取变量参数做业务校验。

代码或图示

query GetUser($id: ID!) { user(id: $id) { name } }

常见误区

  • 把变量拼进查询字符串:失去参数化与校验边界。
  • 变量类型不约束:非法值流入业务。

追问

  • 待确认:变量校验错误在响应中的路径表达,按引擎行为核对。
  • 嵌套输入变量怎么校验?答:输入类型递归校验,错误定位字段路径。

06.8.5.1-086 列表分页与连接(Connection)模式如何设计?

一句话结论

列表字段避免一次性返回全量:用页码偏移或游标连接模式分页;Connection 模式提供节点、边与分页信息(总页数、前后游标);列表字段在复杂度权重中计入乘子,限制单页大小。

概念解释

分页模式:页码偏移适合简单翻页,游标连接适合大数据集与稳定排序。Connection 结构:edges 含节点与游标,pageInfo 含前后页标识。服务端强制页大小上限,游标与排序字段对应。

原理流程

  1. 列表字段接收分页参数。
  2. 按游标/页码取限定范围数据。
  3. 组装节点、游标与分页信息。
  4. 复杂度权重计入列表基数。

代码或图示

Connection:edges { node, cursor } + pageInfo { hasNext, endCursor }

常见误区

  • 列表字段返回全量集合:结果集与内存失控。
  • 游标不对应稳定排序:翻页数据重复或遗漏。

追问

  • 待确认:graphql-kotlin 对 Connection 模式的辅助类型,以生态文档核对。
  • 大集合总数怎么处理?答:可选计数,高精度总数成本高,按场景提供。

06.8.5.1-087 异常分类与 GraphQL 响应结构如何组织?

一句话结论

异常分输入校验、权限拒绝、资源不存在、下游故障与未预期错误;映射到字段错误或整体拒绝;响应保持 data + errors 结构,错误带路径与错误码;未预期异常兜底记录日志,响应中性不泄露堆栈。

概念解释

分类处理决定客户端可操作性:参数错误可修正,权限与不存在是业务结果,下游故障可重试。错误结构统一:路径、消息、错误码。日志侧保留堆栈与 trace。部分成功与整体拒绝的边界按操作语义约定。

原理流程

  1. Fetcher/服务层抛领域异常。
  2. 错误处理器分类映射。
  3. 组装字段错误或整体错误响应。
  4. 兜底异常记录日志并返回中性错误。

代码或图示

{
  "errors": [{ "path": ["user", "orders"], "code": "FORBIDDEN" }],
  "data": { "user": null }
}

常见误区

  • 所有异常返回同一通用错误:客户端无法分支处理。
  • 响应带堆栈与内部类名:信息泄露。

追问

  • 待确认:异常到 GraphQL 错误码的映射扩展点,以模块文档核对。
  • Mutation 部分失败怎么表达?答:按操作设计返回结果列表带逐项错误,避免整体回滚语义不清。

06.8.5.1-088 DataLoader 与事务边界如何划分?

一句话结论

批量加载函数在同一事务或一致读取视图内完成批量查询;请求级 Loader 批次与事务边界对齐,避免同批次读取不一致快照;事务不跨 Loader 批次长期持有,批量函数内短事务完成读写。

概念解释

事务边界影响批量一致性:同一批 key 应在一致视图读取。Loader 批次由调度窗口决定,事务不能跨多个批次悬挂。写操作在 Mutation 解析器内控制事务,读批量加载遵循只读事务。连接与池在事务外管理。

原理流程

  1. 批量函数开启只读短事务。
  2. 一次查询覆盖本批 key。
  3. 返回映射后事务提交释放。
  4. Mutation 写操作在解析器层定事务边界。

代码或图示

读:Loader 批量函数内短事务/一致视图
写:Mutation 解析器事务控制,不跨批次悬挂

常见误区

  • 事务持有整个请求生命周期:连接与锁占用过久。
  • 同批次分批查询走不同视图:结果不一致。

追问

  • 待确认:项目数据访问层事务与 Loader 配合方式,按工程实践核对。
  • 批量写怎么控制?答:在 Mutation 服务层聚合写入,Loader 主要承担读批量加载。

06.8.5.1-089 多租户字段如何隔离?

一句话结论

主体携带租户标识,查询与批量加载条件强制带租户约束;Loader 按租户分组 key,跨租户数据不混入同一批次;字段返回前校验数据归属,租户隔离在数据访问层兜底,不只依赖前端不请求。

概念解释

多租户隔离与水平越权防护一致:查询条件带租户,批量加载按租户过滤。Loader 批次 key 包含租户上下文,避免跨租户合并。DTO 不暴露其他租户标识。联邦/多服务场景租户标识随上下文传递。

原理流程

  1. 认证主体解析租户标识。
  2. 查询与批量加载条件带租户约束。
  3. Loader key 空间按租户隔离。
  4. 返回前校验数据归属。

代码或图示

// 查询条件强制带租户
repository.findByTenant(tenantId, keys)

常见误区

  • 仅在接口层按租户过滤,底层查询不带条件:遗漏接口形成越权。
  • Loader 跨租户批量合并:数据串扰。

追问

  • 待确认:项目多租户数据隔离策略,按架构文档核对。
  • 跨租户管理接口怎么控制?答:单独角色授权,操作记录审计。

06.8.5.1-090 graphql-kotlin 鉴权与复杂度扩展有哪些待核对点?

一句话结论

核对:字段权限注解/扩展、上下文主体访问方式、复杂度与深度限制配置、订阅鉴权钩子、联邦子图鉴权传递;不确定 API 与内置能力标待确认,以官方文档与底层引擎文档为准,不编造注解名称。

概念解释

扩展能力可能由核心模块或第三方组件提供。核对路径:官方文档 -> 模块清单 -> 示例代码 -> 运行验证。自定义规则在无现成扩展时于 Fetcher/入口层实现。版本升级复核扩展兼容。

原理流程

  1. 列出鉴权、复杂度、深度控制需求。
  2. 查官方模块确认支持方式。
  3. 缺失能力在业务层自定义实现。
  4. 用未授权与超限查询用例验证。

代码或图示

核对清单:字段权限 / 上下文主体 / 复杂度 / 深度 / 订阅鉴权 / 联邦传递

常见误区

  • 凭记忆使用不存在的注解名:编译或运行期失效。
  • 只核对 happy path:未授权、超限用例未验证。

追问

  • 待确认:graphql-kotlin 当前版本各扩展点确切 API,以官方仓库文档为准。
  • 扩展升级注意什么?答:上下文接口与权限注解行为可能随版本调整,升级回归安全路径。

06.8.5.1-091 场景:内部服务间 RPC 选 gRPC 还是 GraphQL?

一句话结论

服务间强类型、契约明确、高性能调用选 gRPC;需要灵活聚合字段或前端 BFF 形态选 GraphQL;内部 RPC 通常 gRPC 更贴合,GraphQL 面向消费方按需取数;两者可共存,按调用方与契约形态选型。

概念解释

gRPC:方法契约、流式、紧凑编码、服务间高性能。GraphQL:字段按需选择、聚合查询、客户端驱动形态。内部服务边界稳定时 gRPC 契约清晰;消费方字段需求多变时 GraphQL 灵活。选型不看框架热度,看调用拓扑与运维能力。

原理流程

  1. 识别调用方:内部服务还是前端/BFF。
  2. 评估契约稳定性与字段需求灵活性。
  3. 对比性能、流式与运维成熟度。
  4. 按场景选型,边界内可共存。

代码或图示

服务间:gRPC(方法契约 / 高性能 / 流式)
按需聚合:GraphQL(字段选择 / BFF)

常见误区

  • 内部服务间套 GraphQL 聚合层:增加编排复杂度与故障点。
  • 前端 BFF 用 gRPC:浏览器与字段灵活性不匹配。

追问

  • 待确认:项目服务间调用现状,按架构文档核对。
  • 共存时数据模型如何对齐?答:共享领域模型,适配器层转换 DTO。

06.8.5.1-092 场景:BFF 聚合接口选 GraphQL 还是 REST?

一句话结论

前端需要按需取字段、多资源聚合、迭代频繁选 GraphQL BFF;接口稳定、缓存友好、简单 CRUD 选 REST;GraphQL 需配套复杂度控制、鉴权与观测,REST 缓存与网关生态更成熟。

概念解释

BFF 层聚合后端多个服务。GraphQL 减少前端往返与字段裁剪,但引入查询治理成本。REST 每个端点语义明确,HTTP 缓存与网关规则成熟。团队治理能力与前端契约节奏是决定因素。

原理流程

  1. 评估前端字段需求稳定性与往返次数。
  2. 对比缓存、观测与治理成本。
  3. 选定 BFF 形态并配套防护。
  4. 后端服务契约保持独立。

代码或图示

GraphQL BFF:按需聚合 / 灵活字段 / 需复杂度与权限治理
REST BFF:端点语义清晰 / HTTP 缓存成熟

常见误区

  • 选 GraphQL 却不做复杂度限制:慢查询风险。
  • BFF 直接透传后端服务模型:边界与权限失控。

追问

  • 待确认:项目 BFF 技术选型记录,按架构文档核对。
  • GraphQL 缓存怎么做?答:按查询与主体维度缓存结果,注意私有数据不共享缓存。

06.8.5.1-093 gRPC 能跨公网或浏览器直接调用吗?

一句话结论

gRPC 依赖 HTTP/2,浏览器原生支持受限,公网穿透与客户端生态不如 REST/GraphQL 通用;面向浏览器或开放公网的调用通常经网关转 HTTP,或选用兼容 HTTP/1.1 的方案;内部内网服务间是 gRPC 主场景。

概念解释

铺垫:HTTP/2 在浏览器与代理链路的支持差异、gRPC 浏览器客户端限制。生产中 gRPC 端口不直接对公网暴露。跨网络场景评估协议穿透、客户端库与防火墙支持。浏览器侧 GraphQL/REST 走 HTTP 更通用。

原理流程

  1. 确认调用网络环境(内网/公网/浏览器)。
  2. 核对协议与客户端支持。
  3. 必要时网关协议转换。
  4. 公网入口用 HTTP 兼容方案。

代码或图示

内网服务间:gRPC 直连
浏览器/公网:HTTP 网关(REST/GraphQL),gRPC 不直接暴露

常见误区

  • 假设浏览器可任意直连 gRPC:客户端与协议支持受限。
  • gRPC 端口映射到公网:攻击面与穿透问题。

追问

  • 待确认:目标环境 HTTP/2 与 gRPC 穿透支持,按部署网络核对。
  • 网关转换损失什么?答:流式语义、错误码映射需在网关层适配。

06.8.5.1-094 GraphQL 过度查询导致性能问题如何防范?

一句话结论

多层防护:复杂度与深度限制、列表分页上限、DataLoader 批量优化、查询白名单/持久化查询、按主体限流;监控慢查询与字段耗时;恶意或误写超限查询在执行前拒绝,不进入 Fetcher。

概念解释

过度查询表现:深嵌套、宽字段、大列表、重复关联取数。防护分层:入口约束(复杂度/深度/白名单)、取数优化(Loader 批量)、容量保护(分页/限流)。观测慢查询定位重字段持续优化。

原理流程

  1. 执行前计算复杂度与深度,超限拒绝。
  2. 列表强制分页与大小上限。
  3. 嵌套关联经 Loader 批量加载。
  4. 监控慢查询并迭代字段权重。

代码或图示

防护链:复杂度/深度 -> 分页上限 -> DataLoader 批量 -> 限流 + 慢查询观测

常见误区

  • 只靠数据库索引解决 N+1:查询次数本身失控。
  • 不监控字段耗时:重字段长期未发现。

追问

  • 待确认:项目慢查询日志与字段耗时采集方式,按可观测体系核对。
  • 客户端滥用复杂查询怎么办?答:白名单 + 复杂度阈值 + 配额限流。

06.8.5.1-095 版本演进时字段废弃策略是什么?

一句话结论

废弃字段先标记并通知消费方,保留过渡期双写/兼容,确认无调用后下线;不直接删除字段或改类型;GraphQL 字段废弃与 gRPC 编号预留遵循同一兼容原则,破坏性变更新增字段/版本而非原地改。

概念解释

废弃流程:标注弃用说明 -> 通知消费方迁移 -> 观察调用量 -> 下线清理。过渡期新旧字段并存。契约变更跨团队评审。下线后保留编号/字段名预留,不复用。前端与客户端随版本升级适配。

原理流程

  1. 标记字段 deprecated 与替代方案。
  2. 消费方迁移到新字段。
  3. 监控旧字段调用量归零。
  4. 下线字段并预留命名/编号。

代码或图示

废弃:标记 + 过渡并存 + 调用量观察 + 下线预留
破坏:新增字段/新版本,不改旧契约

常见误区

  • 直接删字段:未迁移客户端查询断裂。
  • 复用废弃字段名/编号:新旧数据解析错乱。

追问

  • 待确认:graphql-kotlin 弃用注解与 SDL 导出标记方式,以文档核对。
  • 版本号怎么暴露?答:按项目 API 版本约定,字段级废弃优先于整体版本切换。

06.8.5.1-096 gRPC 接口如何测试?

一句话结论

服务端测试调用生成 Stub 方法,断言响应消息与状态码;覆盖一元、四类流式、鉴权与错误状态;客户端测试用 Mock 通道/桩替代真实服务端;契约用 proto 兼容性用例校验,不依赖真实网络端口。

概念解释

测试分层:服务实现单测业务逻辑,RPC 层测试 Stub 契约与异常映射,集成测试连测试环境服务端。流式测试验证收发顺序与取消。错误用例覆盖各状态码。生成代码保证测试与契约一致。

原理流程

  1. 装配服务实现注册测试通道。
  2. 经 Stub 发起一元/流式调用。
  3. 断言响应消息字段与状态。
  4. 错误与取消用例分类验证。

代码或图示

测试:Stub 调用 -> 响应消息/状态断言;错误码映射;流收发与取消

常见误区

  • 只测成功一元调用:流式与错误路径未覆盖。
  • 测试依赖真实开发环境服务端:用例不稳定。

追问

  • 待确认:gRPC-Kotlin 测试辅助(测试通道/桩)API,以官方示例核对。
  • 契约兼容怎么测?答:新旧消息编解码互转用例,验证字段缺省与未知字段忽略。

06.8.5.1-097 GraphQL 查询如何断言?

一句话结论

执行查询文档与变量,断言 data 字段值、errors 路径与错误码;覆盖合法查询、未授权字段、超限复杂度与非法变量;测试替身隔离数据源,按查询选择字段验证 Fetcher 取数与批量加载行为。

概念解释

GraphQL 测试入口是查询执行结果,不是单个 REST 端点。断言结构:data 对应查询选择,errors 定位路径。N+1 优化可通过查询数据源调用次数验证。权限与复杂度拒绝在执行前断言。

原理流程

  1. 装配 Schema 与测试替身依赖。
  2. 提交查询文档与变量。
  3. 执行取得 data/errors。
  4. 断言字段值、错误路径与取数调用次数。

代码或图示

// 示意:执行查询并断言(测试 API 以模块文档为准)
val result = executeQuery("query { user(id: \"1\") { name } }")

常见误区

  • 只断言整体成功:字段级错误未发现。
  • 不验证取数次数:N+1 回归未拦截。

追问

  • 待确认:graphql-kotlin 测试执行入口与结果断言 API,以官方文档核对。
  • 订阅如何测试?答:收集流事件序列,断言事件顺序与取消行为。

06.8.5.1-098 gRPC 与 GraphQL 的可观测性有何对比?

一句话结论

gRPC 观测按方法与状态码统计 RPC 指标,追踪跨进程调用链;GraphQL 观测按字段/解析器耗时、查询复杂度与慢查询统计;两者都需 trace 贯穿、错误分类与日志脱敏,GraphQL 额外关注字段级耗时与查询形态。

概念解释

指标维度差异:gRPC 是方法调用维度,GraphQL 是字段执行与查询维度。追踪都依赖元数据/上下文透传。日志记录调用标识与错误原因。GraphQL 单请求内多字段取数,字段耗时定位慢 Fetcher。

原理流程

  1. 入口/拦截器采集调用标识与开始时间。
  2. 执行结束记录状态、耗时与维度标签。
  3. trace 元数据透传跨服务。
  4. 慢调用/字段进入告警与分析。

代码或图示

gRPC:方法 / 状态码 / 延迟分位
GraphQL:字段耗时 / 复杂度 / 慢查询 / 错误路径

常见误区

  • GraphQL 只看接口总耗时:慢字段被平均掩盖。
  • gRPC 不记录状态码分布:失败分类无法统计。

追问

  • 待确认:两者现有指标接入方式,按项目可观测体系核对。
  • 日志记什么?答:调用标识、方法/字段、主体标识、错误码,不记凭据与敏感报文。

06.8.5.1-099 Kotlin 落地这两套技术有哪些常见坑点?

一句话结论

常见坑:proto 字段编号复用、Stub/通道未复用泄漏、异常状态映射混乱;GraphQL 侧 N+1 未批量、Loader 作用域错误、未做复杂度/权限控制、Schema 与代码漂移;清单化在评审与测试中核对。

概念解释

坑点集中在契约边界、资源生命周期与查询治理。gRPC 侧:契约兼容、通道复用、状态码语义。GraphQL 侧:取数批量、请求作用域、查询限制、鉴权字段级。两者都需版本核对与测试覆盖异常路径。

原理流程

  1. 评审契约与生成代码一致性。
  2. 核对通道/Loader 生命周期与作用域。
  3. 覆盖错误、取消与超限用例。
  4. 观测慢调用与慢查询持续优化。

代码或图示

gRPC:编号复用 / 通道泄漏 / 状态映射 / 版本兼容
GraphQL:N+1 / Loader 作用域 / 复杂度权限 / Schema 漂移

常见误区

  • 生成代码被手改:下次生成丢失。
  • 请求级对象存全局:并发串扰。
  • 上线前不做契约兼容与超限查询测试。

追问

  • 待确认:项目实际踩坑记录与基线配置,按工程文档核对补充。
  • 新人接入先读什么?答:proto/SDL 契约、Loader 与上下文约定、错误码映射表。

06.8.5.1-100 Kotlin 生态下 gRPC 与 GraphQL 的选型边界如何总结?

一句话结论

gRPC 适合内部服务间强类型 RPC、流式与高性能调用;GraphQL 适合消费方按需聚合、BFF 与灵活字段场景;Kotlin 协程模型两者都能适配,落地关键是契约治理、资源生命周期与查询/调用防护,按调用拓扑与团队能力定稿。

概念解释

选型边界:调用方是谁(服务/前端)、契约稳定性、字段灵活性、流式需求、运维观测成熟度。两者不是互斥替代:内网 gRPC、边缘 GraphQL/REST 可分层共存。框架能力以当前版本生态为准,不确定组件成熟度标待确认后验证。

原理流程

  1. 梳理调用拓扑与消费方形态。
  2. 对比契约、性能、流式与治理成本。
  3. 概念验证关键链路与防护能力。
  4. 分层选型并明确边界与演进策略。

代码或图示

gRPC:内部服务 / 方法契约 / 流式 / 紧凑编码
GraphQL:BFF / 按需取数 / 字段聚合 / 查询治理

常见误区

  • 凭单点性能或潮流选型:忽略治理与运维成本。
  • 同一系统两套协议边界不清:重复聚合与权限失控。

追问

  • 待确认:gRPC-Kotlin 与 graphql-kotlin 当前生态成熟度,以官方仓库与社区状态核对。
  • 后续演进怎么评估?答:按服务拆分节奏、前端需求变化与组件成熟度定期复核选型。

参考来源

待整理清单

  • [ ] 核对 gRPC-Kotlin 生成插件/运行时坐标、通道与 Stub API、异常类型与状态码枚举
  • [ ] 核对四类流式 RPC 在 Kotlin 生成代码中的收发接口与协程/Flow 形态
  • [ ] 核对拦截器接口、元数据读写、deadline/keepalive 与健康检查配置
  • [ ] 核对 graphql-kotlin 模块坐标、Schema 生成扫描配置与上下文访问 API
  • [ ] 核对 DataLoader 注册作用域、批量函数签名与缓存默认行为
  • [ ] 核对 Subscription 传输协议、Federation 实体注解与字段权限/复杂度扩展点
  • [ ] 补充项目实际 proto/SDL 契约示例、拦截器与 Loader 装配代码