06.8.1.2 插件、认证与内容协商
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.8 Kotlin 后端 / 06.8.1 Ktor 框架
本节要解决的问题
- Ktor 插件机制如何装配,如何开发自定义插件;认证插件中 provider、principal、challenge 的模型如何工作。
- JWT、Basic、Session 认证如何落地,多认证如何组合;ContentNegotiation 如何接入 kotlinx.serialization 与 Jackson。
- CORS、压缩、缓存、限流、校验与安全头如何配置;版本基线 Ktor 3.x、Kotlin 2.x,不确定 API 标「待确认」并写验证点。
06.8.1.2-001 Ktor 插件机制整体如何运作?
一句话结论
插件通过 install 装配到 Application:安装器读取配置、在管道阶段注册拦截器、必要时注册进程级对象;请求经过对应阶段时触发插件逻辑,横切能力以插件为单位复用。
概念解释
插件是 Ktor 扩展框架能力的标准单元:官方提供认证、序列化、CORS、压缩等插件,业务也可自定义。插件不直接接管请求,而是在管道节点上包裹 Handler,与框架其余部分通过 Call、attributes 协作。
原理流程
- 模块内
install(SomePlugin) { 配置 }。 - 安装器构造配置对象并注册拦截器到管道阶段。
- 请求进入阶段时执行插件前置/后置逻辑。
- 插件所需共享对象写入 Application 或 Call 属性。
代码或图示
install(ContentNegotiation) {
json(Json { prettyPrint = true })
}
常见误区
- 把插件当成独立服务启动:插件只是管道行为单元。
- 在 Handler 内重复实现插件已覆盖的横切逻辑:分支遗漏。
追问
- 插件配置在什么时机执行?答:装配期,详见本节后续题目。
- 插件能改路由表吗?答:一般不能,路由表在装配阶段确定。
06.8.1.2-002 Plugin 与旧版 Feature 概念是什么关系?
一句话结论
现代 Ktor 以 Plugin 描述符与安装器为扩展单元;早期版本的 Feature 概念在演进中被插件机制替代,旧写法可能已弃用;具体改名与替代 API 以版本迁移文档为准,未核对前标「待确认」。
概念解释
面试只需说明扩展机制的演进脉络:从早期 Feature 装配器到当前插件描述符模型。不要凭记忆断言旧类名在 3.x 仍可用;代码迁移以编译告警和官方 changelog 为准。
原理流程
- 对照编译告警识别弃用的旧扩展写法。
- 查迁移指南找到对应插件安装入口。
- 替换为当前插件描述符 API。
- 回归验证拦截行为。
代码或图示
核对路径:编译告警 -> 官方迁移文档 -> 当前插件 install 写法
常见误区
- 把旧 Feature 笔记当当前 API 答案:版本行为可能已变。
- 只替换类名不核对拦截阶段:行为层次可能不同。
追问
- 待确认:Ktor 3 中旧 Feature 相关 API 的废弃状态,以官方文档核对。
- 自定义插件当前推荐入口是什么?答:
createApplicationPlugin,签名见后续题目。
06.8.1.2-003 install 时插件配置闭包在什么时机执行?
一句话结论
配置闭包在装配期(引擎启动、Application 构建阶段)执行一次,此时没有任何请求;请求期逻辑必须由闭包注册的拦截器在 Call 上执行,不能在闭包里读取请求数据。
概念解释
装配期负责构造插件策略与默认值;请求期才接触 Call。混淆两个阶段会写出拿不到上下文的代码,或把请求级状态错误地固化进进程级配置。
原理流程
- 引擎加载模块,进入装配流程。
- install 调用配置闭包,读取环境配置。
- 注册请求期拦截器。
- 启动后请求到来,拦截器才访问 Call。
代码或图示
install(Authentication) {
// 装配期:定义 provider 与策略
jwt("jwt-auth") { /* ... */ }
}
常见误区
- 闭包里取
call.parameters:装配期无 Call,编译或运行期报错。 - 在闭包内缓存每请求值:进程级单例被请求污染。
追问
- 配置需要按环境变化怎么办?答:装配期从 environment.config 读取,按环境给不同策略。
- 插件能在装配期起后台协程吗?答:可以,但要绑定应用生命周期并在停机时取消。
06.8.1.2-004 插件描述符由哪些部分组成?
一句话结论
一个插件描述符包含名称、配置构造器、安装器逻辑;安装器内完成拦截注册、属性写入与生命周期订阅;现代 API 通过工厂函数生成描述符,业务方只通过 install 引用。
概念解释
名称用于识别与排障;配置类持有可选项;安装器是行为装配点。理解组成有助于读官方插件源码和写自定义插件,不需要背诵内部类名,不确定处以源码为准。
原理流程
- 定义插件配置类与默认值。
- 工厂函数生成带名称的描述符。
- 安装器内拦截管道、挂属性、订阅事件。
- install 时把配置闭包交给描述符。
代码或图示
PluginDescriptor:
- 名称(调试标识)
- 配置对象(策略参数)
- 安装器(拦截注册 / 属性 / 生命周期)
常见误区
- 把配置对象当请求上下文用:生命周期不同。
- 插件名称与其他插件重名:排障时难以定位。
追问
- 待确认:Ktor 3 插件描述符接口与工厂函数签名,以官方插件文档核对。
- 配置可不可变?答:建议装配后视为不可变,请求期不修改。
06.8.1.2-005 内置插件与自定义插件共用同一套机制吗?
一句话结论
共用同一套管道与安装机制:官方插件只是由框架维护的描述符,自定义插件遵循同样的 install 与拦截注册方式;区别在成熟度、默认配置与生态集成,不在运行时待遇。
概念解释
理解这一点后,读官方插件行为可以套用管道阶段模型;自定义插件能复用 Call、attributes、monitor 等基础能力。官方插件处理了边界与兼容,自研插件需自行覆盖异常与配置校验。
原理流程
- 识别要实现的横切能力属于哪个管道阶段。
- 按官方插件相同方式注册拦截。
- 自行补配置校验、异常兜底与测试。
- 复用框架提供的 Call 与属性 API。
代码或图示
// 自定义插件与官方插件都经 install 挂到同一 Application
install(MyPlugin) { setting = true }
常见误区
- 认为自研插件能拿到特权内部接口:只能用公开扩展能力。
- 忽略配置校验:自研插件非法输入可能启动期不失败、请求期才崩。
追问
- 自研插件能依赖官方插件吗?答:可在同一管道协作,注意安装顺序与属性约定。
- 插件发布复用形式?答:抽成公共模块函数或独立库,按项目依赖管理引入。
06.8.1.2-006 插件如何访问 Application 环境与配置?
一句话结论
安装器通过 application.environment.config 读取配置键,装配期解析为插件策略;请求期拦截器引用已解析的配置对象,不重复读配置源。
概念解释
环境配置包括应用配置、开发模式标识与日志。插件应提供默认值并在装配期校验必填项,缺失时启动快速失败;敏感配置从环境变量或密钥管理注入。
原理流程
- 安装器获取 Application 环境。
- 按 key 读取配置,合并默认值。
- 校验取值范围,构造不可变策略。
- 拦截器闭包引用策略对象。
代码或图示
val timeout = application.environment.config
.propertyOrNull("my.timeoutMs")?.getString()?.toLong() ?: 1000L
常见误区
- 请求期才读配置文件:每次 IO 且失败滞后。
- 配置对象留可变并在请求期改:多请求竞争。
追问
- 待确认:配置读取 API 在 Ktor 3 中的方法名与可空行为,以官方文档核对。
- 配置非法何时报错?答:装配期抛异常,阻止上线。
06.8.1.2-007 插件的进程级状态应该放在哪里?
一句话结论
插件装配期构造的无状态客户端、计数器、配置策略放 Application attributes(进程级);单次请求解析出的主体、临时值放 Call attributes(请求级),两者生命周期不能混用。
概念解释
进程级对象在整个应用生命周期复用,必须线程安全;请求级对象随请求结束销毁。把请求数据存进程属性会并发串号,把全局客户端存 Call 会每次请求重建。
原理流程
- 判断对象生命周期:跨请求复用还是单次使用。
- 进程级对象装配时写入 application.attributes。
- 请求级值挂 call.attributes。
- 请求结束只清理 Call 属性。
代码或图示
val ClientKey = AttributeKey<MetricsClient>("MetricsClient")
application.attributes.put(ClientKey, MetricsClient(config))
常见误区
- 在单例字段里缓存当前登录用户:并发串号。
- 把连接池挂到 Call:请求结束被回收。
追问
- 属性表键为什么用类型化 Key?答:避免字符串重名与弱类型强转。
- 进程级状态如何释放?答:订阅停止事件关闭,见后续题目。
06.8.1.2-008 插件拦截器可以挂在哪些管道阶段?
一句话结论
插件按行为性质选择阶段:认证、CORS 等前置检查挂插件/调用前阶段,响应包装与压缩包裹 Handler,日志统计挂监控阶段;阶段选错会导致行为过早或过晚。
概念解释
阶段划分与框架管道一致:前置准备、插件装配、调用处理、结果监控。前置类必须在 Handler 之前拦截,观察类放在能拿到最终结果的位置。具体阶段常量名以版本为准。
原理流程
- 明确插件行为在请求链中的位置。
- 选取对应阶段注册拦截器。
- 前置逻辑在 proceed 前,收尾在 proceed 后。
- 监控类只读最终状态与异常。
代码或图示
intercept(ApplicationCallPipeline.Plugins) {
// 前置:校验、补充请求信息
proceed()
// 后置:补充响应头
}
常见误区
- 鉴权挂监控阶段:Handler 已执行,挡不住请求。
- 日志挂前置阶段:拿不到最终状态码。
追问
- 待确认:Ktor 3 可用阶段常量与顺序,以官方 pipeline 文档核对。
- 一个插件能挂多个阶段吗?答:可以,按职责分别注册。
06.8.1.2-009 插件如何读取和修改响应?
一句话结论
拦截器在 proceed 后读取响应状态与头,可补充响应头;响应体由序列化插件或 Handler 生成,body 提交后不可回读重写,统一包装应在响应生成层处理。
概念解释
响应修改能力分层:状态码与头在提交前可改,body 内容在序列化/响应构造阶段介入。插件想统一包一层 envelope,应作用于响应对象序列化前,而不是写出后改写字节流。
原理流程
- Handler 产出响应对象。
- 序列化插件转为 body 并写头。
- 后置拦截补充或覆盖未提交的头。
- body 提交后进入网络写出。
代码或图示
intercept(ApplicationCallPipeline.Plugins) {
proceed()
call.response.headers.append("X-App-Version", version)
}
常见误区
- body 写出后再读取重写:缓存行为不确定。
- 多个插件各自包响应体:格式互相覆盖。
追问
- 状态码能被后置拦截改吗?答:未提交前可以,已提交忽略。
- 响应体包装在哪做合适?答:内容协商层或自定义响应包装插件。
06.8.1.2-010 插件依赖另一个插件时如何声明与协作?
一句话结论
跨插件协作通过管道顺序与 attributes 约定:被依赖插件先安装,把共享对象写入属性;依赖插件在之后阶段读取。依赖关系应在文档与装配顺序上明确,不依赖隐式偶然顺序。
概念解释
典型协作:认证插件写入 principal,后续授权或日志插件读取;序列化插件先于响应包装。安装顺序决定包裹层次,属性约定决定数据契约。隐式依赖在重构时容易断裂。
原理流程
- 明确数据生产方与消费方。
- 生产插件先安装并写属性 Key。
- 消费插件后安装,按 Key 读取并判空。
- 在模块装配中固化顺序。
代码或图示
认证插件(生产 principal) -> 授权/日志插件(消费 principal)
常见误区
- 消费插件假设生产插件一定先装:顺序调换后取不到主体。
- 属性 Key 命名不统一:跨插件取值失败。
追问
- 待确认:Ktor 3 是否提供插件依赖声明 API,以官方文档核对。
- 取不到依赖对象怎么办?答:装配期校验或请求期快速失败,不静默放行。
06.8.1.2-011 插件安装失败如何快速定位?
一句话结论
安装失败多为配置非法、缺失依赖或阶段冲突:先看装配期异常堆栈与插件名称,核对配置值与安装顺序,再用最小模块复现;请求期才暴露的问题多为阶段挂错或属性取不到。
概念解释
启动期失败:配置解析、必填项缺失、重复安装冲突。请求期失败:拦截阶段错误、上游插件未提供属性、响应被重复包装。两类问题定位路径不同,不要混在一起猜。
原理流程
- 区分失败时机:启动装配还是请求处理。
- 读异常堆栈定位插件与阶段。
- 核对配置项与依赖插件顺序。
- 最小模块复现后修复。
代码或图示
启动失败:配置 / 依赖缺失 / 重复安装
请求失败:阶段错误 / 属性缺失 / 响应冲突
常见误区
- 启动失败就改业务代码:问题常在装配配置。
- 忽略插件名称日志:多个同类插件时分不清。
追问
- 如何输出插件装配清单?答:开发期日志或装配打印,具体能力以版本为准。
- 配置非法应在哪层拦截?答:插件安装器校验,启动快速失败。
06.8.1.2-012 插件配置 DSL 如何定义?
一句话结论
为插件定义配置类(属性带默认值),安装工厂接收配置类构造器,install 闭包内修改属性;配置项按必填/可选区分,提供校验方法,保持装配后不可变。
概念解释
DSL 的价值是调用方可读、配置集中。配置类只放策略参数,不放请求上下文;复杂默认值在类初始化或安装器内解析。校验在安装器统一执行,避免每个请求重复检查。
原理流程
- 定义配置类与字段默认值。
- 工厂函数绑定配置类。
- install 闭包覆盖可选值。
- 安装器校验后冻结为策略对象。
代码或图示
class MyPluginConfig {
var timeoutMs: Long = 1000
var enabled: Boolean = true
}
常见误区
- 配置类暴露可变集合被请求期修改:并发风险。
- 配置项没有默认值与校验:调用方漏配时行为不确定。
追问
- 嵌套配置怎么组织?答:配置类内部聚合成组,DSL 层级与之一致。
- 待确认:工厂函数配置构造器参数签名,以官方 createApplicationPlugin 文档核对。
06.8.1.2-013 插件如何订阅应用生命周期事件?
一句话结论
通过 application.monitor.subscribe(事件) 订阅启动停止等生命周期节点,在停止事件中释放后台协程、客户端与连接池;订阅逻辑自行容错,避免一个清理失败阻断其余。
概念解释
生命周期订阅用于资源持有型插件:后台轮询、订阅消费者、共享客户端。事件触发时机在装配之后、停机流程之中;订阅回调不能再依赖已关闭的其他资源。
原理流程
- 插件安装时订阅启动/停止事件。
- 启动事件中初始化后台任务。
- 停止事件中取消 Job、关闭客户端。
- 清理异常记录日志但不中断其余释放。
代码或图示
application.monitor.subscribe(ApplicationStopping) {
background.cancel()
client.close()
}
常见误区
- 不订阅停止事件:后台协程与连接随进程残留。
- 清理流程抛异常未捕获:后续资源得不到释放。
追问
- 待确认:Ktor 3 生命周期事件类型名称,以官方文档核对。
- 启动事件适合做什么?答:预热缓存、建立连接,不要阻塞启动过久。
06.8.1.2-014 引入第三方插件要核对哪些点?
一句话结论
核对版本基线与兼容性、维护状态、配置边界、线程安全与异常处理、依赖体积与漏洞;在测试环境验证行为后再引入生产,不因为功能示例可用就直接上线。
概念解释
第三方插件可能绑定特定 Ktor 版本、自带传递依赖,或在请求期持有可变状态。评审重点:是否线程安全、异常是否吞掉、配置是否可观测、是否有安全相关默认值。
原理流程
- 核对插件版本与 Ktor/Kotlin 基线兼容。
- 审查源码或文档的线程模型与异常处理。
- 测试环境覆盖正常与失败路径。
- 评估依赖体积、漏洞维护与替代方案。
代码或图示
评审清单:版本兼容 / 维护活跃度 / 线程安全 / 异常兜底 / 依赖与漏洞
常见误区
- 只看 README 示例:生产边界行为未验证。
- 引入后不跟踪升级:已知漏洞长期暴露。
追问
- 待确认:插件坐标与版本兼容矩阵,以官方仓库与发布说明核对。
- 插件出问题如何回退?答:按模块隔离装配,可关闭插件或替换为自研实现。
06.8.1.2-015 如何用 createApplicationPlugin 写最小自定义插件?
一句话结论
用工厂函数创建插件描述符,安装器内注册一个管道拦截器;最小插件只做前置或后置动作,配置类可选;写完经 install 装配并在测试中验证拦截触发。
概念解释
最小示例帮助理解装配链路:描述符 -> 安装器 -> 拦截器 -> Call。先让插件能进入管道,再逐步加配置、属性与生命周期逻辑。API 签名以版本为准。
原理流程
- 调用插件工厂并命名。
- 安装器内 intercept 注册逻辑。
- 模块内 install 该插件。
- 测试发起请求观察拦截执行。
代码或图示
val LoggingPlugin = createApplicationPlugin("LoggingPlugin") {
onCall { call ->
application.log.info("${call.request.httpMethod} ${call.request.uri}")
}
}
常见误区
- 拦截器内直接读请求体:流可能已被消费。
- 插件未 install:拦截器自然不触发。
追问
- 待确认:
onCall对应的管道阶段与可用回调签名,以官方插件文档核对。 - 最小插件需要配置类吗?答:无策略参数时可省略,需要可选项时再加。
06.8.1.2-016 自定义插件配置类如何组织?
一句话结论
配置类按策略分组,字段带默认值,提供校验方法;安装器把闭包修改后的配置转成不可变策略对象供拦截器使用,避免请求期直接触碰可变配置。
概念解释
配置组织原则:必填项显式声明,可选项给安全默认值;敏感配置不在配置类里硬编码。嵌套策略用内部类分组,DSL 调用方按组阅读。校验失败在装配期抛出。
原理流程
- 定义配置类与默认值。
- install 闭包覆盖配置。
- 安装器校验必填与取值范围。
- 生成不可变策略供拦截器引用。
代码或图示
class RetryConfig {
var maxAttempts: Int = 3
var backoffMs: Long = 200
fun validate() { require(maxAttempts >= 0) }
}
常见误区
- 配置集合直接暴露可变内部状态:外部可改默认值。
- 缺少校验:非法配置进入请求期才报错。
追问
- 配置需要从环境读吗?答:安装器可合并 environment.config 与闭包覆盖。
- 策略对象放哪里?答:装配期构造,挂 Application 属性或闭包捕获。
06.8.1.2-017 onCall 钩子与 intercept 有什么区别?
一句话结论
onCall 是插件工厂提供的语义化回调,对应调用阶段的拦截;intercept(阶段) 是更底层的管道注册,可选择任意阶段与 proceed 前后逻辑。语义钩子简化常见场景,需要多阶段或包裹控制时用底层拦截。
概念解释
语义钩子把「在调用时执行」封装好,调用方不必选阶段;底层 intercept 能控制 proceed 顺序、前置后置包裹与短路。两者最终都注册到管道节点,行为层次需结合版本文档确认。
原理流程
- 场景只需要调用时观察:用 onCall 钩子。
- 需要前置校验、短路或包裹响应:用 intercept 选阶段。
- 钩子内部仍注册为管道拦截器。
- 复杂插件可组合多个钩子与拦截。
代码或图示
// 语义钩子:调用时动作
onCall { /* ... */ }
// 底层拦截:阶段与 proceed 可控
intercept(ApplicationCallPipeline.Plugins) { proceed() }
常见误区
- 把需要短路的逻辑写进只观察的钩子:无法阻断 Handler。
- 假设钩子对应固定阶段且版本不变:以文档核对。
追问
- 待确认:Ktor 3 插件工厂提供的全部回调名称与阶段语义,以官方文档核对。
- 钩子能改响应吗?答:能否改 body 取决于回调时机与响应提交状态。
06.8.1.2-018 插件如何在请求级 attributes 传递数据?
一句话结论
用类型化 AttributeKey 把解析出的值写入 call.attributes,同请求后续拦截器或 Handler 按 Key 读取;Key 在插件间共享定义,读取判空,请求结束随 Call 销毁。
概念解释
请求级属性是插件与 Handler 解耦的数据通道:认证插件放主体,追踪插件放 trace id。不要把请求级值写进 Application 属性;Key 带类型,避免弱类型强转。
原理流程
- 定义共享 AttributeKey 与类型。
- 生产插件在拦截器写 call.attributes。
- 消费方按 Key 读取并判空。
- 请求结束属性随 Call 释放。
代码或图示
val TraceKey = AttributeKey<String>("TraceId")
call.attributes.put(TraceKey, traceId)
val traceId = call.attributes[TraceKey]
常见误区
- 跨请求复用 Call 属性:新请求取不到旧值。
- 字符串键取值:强转失败且易重名。
追问
- 待确认:属性读取 API 的可空与缺失行为,以官方文档核对。
- 属性能存大对象吗?答:应存引用,大对象生命周期另行管理。
06.8.1.2-019 自定义插件如何做前置校验并短路?
一句话结论
在前置阶段拦截器内判定条件,不满足时直接 respond 错误响应且不调用 proceed,管道短路;校验维度可以是请求头、参数、主体或开关,短路响应保持统一错误结构。
概念解释
短路用于拒绝类横切逻辑:缺凭据、非法来源、超限流。校验通过才 proceed 进入下游。短路后不再调用 proceed,避免重复响应;拒绝原因写日志,响应体中性。
原理流程
- 前置拦截读取请求所需信息。
- 校验失败:构造错误响应并 respond。
- 不 proceed,结束本次拦截。
- 通过则 proceed 放行。
代码或图示
intercept(ApplicationCallPipeline.Plugins) {
if (call.request.headers["X-Api-Key"].isNullOrBlank()) {
call.respond(HttpStatusCode.Unauthorized)
return@intercept
}
proceed()
}
常见误区
- respond 后仍 proceed:重复响应或异常。
- 短路响应不带状态码:默认 200 语义错误。
追问
- 短路后子树拦截执行吗?答:不进入路由子树。
- 校验信息从哪里取?答:请求头、参数、已解析主体或属性。
06.8.1.2-020 插件如何包裹响应做统一包装?
一句话结论
在调用阶段包裹 proceed:Handler 产出响应后由插件统一映射为外层结构(如 envelope 包装、错误归一);包装逻辑作用于响应对象,注意与序列化插件协作顺序,body 提交后不再改写。
概念解释
统一包装适合成功/错误响应同构输出。插件读取响应对象与状态,转换为包装结构;直接改写已提交 body 不可靠。包装规则要避开文件下载、流式响应等非 JSON 场景。
原理流程
- 拦截器 proceed 拿到响应结果。
- 按状态与类型决定是否包装。
- 重写响应为包装结构。
- 序列化插件最终输出 body。
代码或图示
intercept(ApplicationCallPipeline.Call) {
proceed()
// 仅对 JSON 响应做包装;具体读取响应 API 以版本为准
}
常见误区
- 对二进制/流式响应包文本外壳:破坏下载与分块。
- 多个包装插件叠加:层级错乱。
追问
- 待确认:拦截器中读取响应对象与重写响应的 API,以官方文档核对。
- 错误响应在哪一层归一?答:异常处理插件或响应包装插件,二选一避免重复。
06.8.1.2-021 插件里启动后台协程要注意什么?
一句话结论
后台协程必须绑定应用 Job 生命周期,持有引用并在停止事件取消;不要挂请求作用域,不要用全局作用域放任泄漏;任务异常要有人消费并记录日志。
概念解释
插件常需要定时刷新缓存、推送订阅或批量同步。这类任务生命周期与应用一致,区别于请求协程。未取消的后台任务在停机后仍占用线程与连接,是常见泄漏源。
原理流程
- 装配期创建 SupervisorJob 作为根。
- 后台任务挂该 Job 启动。
- 订阅停止事件取消根 Job 并等待结束。
- 任务异常捕获记录,不静默崩溃。
代码或图示
val background = SupervisorJob()
application.monitor.subscribe(ApplicationStopping) { background.cancel() }
常见误区
- 用 GlobalScope 起任务:停机取消不到。
- 后台任务持有 Call 引用:请求结束后悬垂。
追问
- 后台任务失败要重试吗?答:按任务性质配置有限重试与告警,避免无限循环。
- 待确认:应用级 Job 可访问方式,以源码/文档核对。
06.8.1.2-022 插件如何订阅停机事件释放资源?
一句话结论
在安装期订阅停止事件,回调内按逆序取消后台任务、关闭客户端与池;每个释放动作容错并记录失败,设等待上限避免僵死资源拖住停机流程。
概念解释
资源释放顺序与创建相反:先停任务接收新工作,再关连接池。停止回调中不要再发起远程调用等待响应,否则停机延迟。释放失败应记录但继续清理其余资源。
原理流程
- 安装期注册停止回调。
- 停机触发:取消后台 Job。
- 关闭客户端、池与临时资源。
- 异常捕获记录,流程继续。
代码或图示
application.monitor.subscribe(ApplicationStopping) {
runCatching { background.cancel() }
runCatching { client.close() }
}
常见误区
- 先关池再等任务结束:任务借已关闭池报错。
- 一个资源释放异常中断后续清理:其余资源泄漏。
追问
- 待确认:停止事件回调是否提供等待机制与超时参数,以官方文档核对。
- 临时文件在哪删?答:任务结束或停机时清理,避免残留。
06.8.1.2-023 自定义插件如何写测试?
一句话结论
用测试应用装配插件,发起请求断言拦截行为:前置短路、属性写入、响应包装与日志;外部依赖替换为测试替身,覆盖正常、拒绝与异常路径。
概念解释
插件测试聚焦管道行为,不依赖真实端口。断言点:是否进入拦截、属性 Key 是否写入、短路响应状态码、包装结构是否正确。配置不同默认值各跑一遍用例。
原理流程
- 测试构造 Application 装配目标插件。
- 注入测试替身依赖。
- 发起各类请求。
- 断言响应、属性与调用交互。
代码或图示
testApplication {
install(MyPlugin) { /* 测试配置 */ }
val res = client.get("/")
assertEquals(HttpStatusCode.Unauthorized, res.status)
}
常见误区
- 只测放行路径:拒绝与异常分支未覆盖。
- 断言日志文本:脆弱,应断言行为与状态。
追问
- 待确认:测试启动器 API 在 Ktor 3 中的名称,以官方测试文档核对。
- 插件单测能否脱离 Application?答:纯策略逻辑可单测,管道行为需测试应用。
06.8.1.2-024 自研插件常见坑点有哪些?
一句话结论
常见坑:阶段挂错导致鉴权失效、装配期读取请求上下文、请求值误存进程属性、重复安装行为叠加、资源未随停机释放、异常被吞掉无日志;逐一在评审与测试中核对。
概念解释
这些坑本质都是生命周期与阶段边界混淆。清单化排查:阶段是否正确、两个生命周期是否混用、安装是否幂等、资源是否释放、异常是否可见。自研插件上线前应过一遍该清单。
原理流程
- 评审插件阶段与短路逻辑。
- 核对属性生命周期归属。
- 检查重复安装与资源释放。
- 验证异常路径有日志与兜底响应。
代码或图示
坑点清单:阶段 / 上下文时机 / 属性归属 / 重复安装 / 资源释放 / 异常可见性
常见误区
- 上线后才发现鉴权在 Handler 之后:测试未覆盖匿名请求。
- 插件异常只记本地控制台:生产排障无记录。
追问
- 插件如何避免重复安装?答:安装器做重复保护或在装配结构上保证单点安装。
- 与官方插件冲突怎么办?答:核对阶段与包装层次,必要时二选一。
06.8.1.2-025 Authentication 插件的整体模型是什么?
一句话结论
Authentication 插件管理命名认证提供者,按引用把提供者挂到路由子树;请求经提供者校验后产出 principal,失败时触发 challenge 返回 401/403;授权(角色权限)在认证之后的 Handler 或拦截层完成。
概念解释
认证回答「你是谁」,授权回答「你能做什么」。插件内注册多个 provider(JWT、Basic、Session 等),路由块引用 provider 名称。校验通过把主体放入 Call,未通过由 challenge 生成响应。
原理流程
- install(Authentication) 内定义命名 provider。
- 路由块
authenticate("name")引用 provider。 - 请求进入 provider 校验凭据,成功产出 principal。
- 失败触发 challenge,返回未认证/无权限响应。
代码或图示
install(Authentication) {
jwt("jwt-auth") { /* 校验与主体映射 */ }
}
routing {
authenticate("jwt-auth") {
get("/me") { /* principal 可用 */ }
}
}
常见误区
- 把权限判断写进认证 provider:认证与授权职责混杂。
- 只注册 provider 不引用:受保护路由没有实际校验。
追问
- 待确认:Ktor 3 Authentication 插件 DSL 与 provider 类型名称,以官方文档核对。
- 一个路由块能引用几个 provider?答:可组合多个,选择规则见多认证题目。
06.8.1.2-026 认证与授权的边界在哪里?
一句话结论
认证完成身份识别并写入 principal;授权基于主体判断角色、权限、数据归属,放在后续拦截层或 Handler 内;两者分层实现,避免在凭据校验逻辑里夹杂业务权限判断。
概念解释
认证失败对应 401(未登录/凭据无效),授权失败对应 403(已识别但无权)。主体携带角色与标识,授权策略按资源与主体关系判定。分层后可独立替换认证方式(Token/Session)。
原理流程
- 认证 provider 校验凭据,构造 principal。
- 授权层读取 principal 与资源要求。
- 通过则进入 Handler,否则 403。
- 数据级权限在 Handler 内按归属过滤。
代码或图示
认证:凭据 -> principal(401 失败)
授权:principal + 资源 -> 允许/拒绝(403 失败)
常见误区
- 401/403 混用:客户端与网关无法区分未登录和无权限。
- 授权散落在 Handler 各处:遗漏接口形成越权入口。
追问
- 角色校验放哪一层?答:可在授权拦截按子树统一,数据归属在 Handler 内判。
- 主体里放什么?答:用户标识、角色/权限等认证结果,不放敏感明文凭据。
06.8.1.2-027 AuthenticationProvider 与命名 provider 是什么关系?
一句话结论
每个认证策略对应一个 provider,可在安装时命名;路由块通过名称引用对应 provider;命名允许同一插件下共存 JWT、Basic、Session 等多套策略并按子树选用。
概念解释
provider 封装校验规则与 challenge 行为。名称是路由引用句柄,同一 provider 可被多个子树复用。未命名 provider 的默认引用方式以版本 API 为准,不凭记忆断言。
原理流程
- 安装 Authentication 时声明 provider 并命名。
- 配置校验逻辑、主体映射与挑战响应。
- 路由块按名称引用。
- 请求匹配到引用该 provider 的子树时执行校验。
代码或图示
install(Authentication) {
basic("basic-auth") { /* ... */ }
jwt("jwt-auth") { /* ... */ }
}
常见误区
- 多个 provider 同名:引用指向不确定。
- provider 配置写好但路由未引用:接口裸奔。
追问
- 待确认:默认(未命名)provider 的引用规则,以官方文档核对。
- provider 能共享配置吗?答:公共凭据解析可抽公共函数,provider 各自组装。
06.8.1.2-028 principal 是什么,如何存取?
一句话结论
principal 是认证成功后代表当前身份的类型化对象,由 provider 写入 Call;Handler 或授权层通过 call.principal<T>() 按类型取出,取不到表示未认证。
概念解释
principal 替代在请求里反复解析用户名:认证结果一次解析、下游复用。类型化主体携带用户标识、角色等;不要把原始密码、令牌原文存进 principal。不同 provider 可产出不同 principal 类型。
原理流程
- provider 校验通过,构造 principal 对象。
- 写入 Call 认证上下文。
- 下游按类型读取 principal。
- 读取失败按未认证处理。
代码或图示
data class UserPrincipal(val userId: String, val roles: Set<String>)
val principal = call.principal<UserPrincipal>()
常见误区
- 在 Handler 里重新解析令牌:重复校验且可能拿到不一致结果。
- principal 存原始凭据:日志与序列化泄露风险。
追问
- 待确认:principal 读写 API 名称与多类型取值行为,以官方文档核对。
- 主体能跨请求缓存吗?答:不能,每请求重新认证产出。
06.8.1.2-029 challenge 机制如何工作?
一句话结论
认证失败时 provider 触发 challenge:构造未认证响应(状态码、头、体),Basic 等方案还会返回协商头;challenge 决定客户端如何被引导重新提供凭据,而不是由 Handler 自己返回 401。
概念解释
challenge 是认证插件的失败响应出口:区分缺凭据、凭据无效、令牌过期等情形,生成对应状态与头。自定义响应结构可在 challenge 层归一,避免每个受保护接口手写拒绝逻辑。
原理流程
- provider 校验未通过或未提供凭据。
- 调用 challenge 流程生成响应。
- 按方案设置状态码与协商头。
- 响应短路,不进入 Handler。
代码或图示
缺凭据 / 无效凭据 / 过期 -> challenge -> 401(或 403 场景)-> 响应短路
常见误区
- Handler 内自行返回 401:绕过 challenge 统一规则。
- 所有失败都返回同样消息:无法区分过期与无效,排障困难。
追问
- 待确认:Ktor 3 challenge 自定义配置入口,以官方认证文档核对。
- 403 由 challenge 产生吗?答:未认证归 401,已识别无权限归 403,后者多在授权层。
06.8.1.2-030 未认证与无权限响应有什么区别?
一句话结论
未认证(401)表示身份缺失或凭据无效,需重新登录/提供凭据;无权限(403)表示身份已识别但不具备该资源权限;两者状态码、响应头与客户端处理流程不同,不可混用。
概念解释
401 常携带认证协商头,403 不引导重新认证。响应体消息保持中性,不枚举用户是否存在。审计日志分别记录两类拒绝,便于发现爆破与越权尝试。
原理流程
- 认证阶段失败 -> 401 challenge。
- 认证通过、授权阶段失败 -> 403。
- 响应结构统一,消息中性。
- 拒绝事件记录主体标识(若有)与路径。
代码或图示
401:匿名 / 凭据无效 -> 引导重新认证
403:已登录但权限不足 -> 拒绝访问
常见误区
- 登录用户访问越权资源返回 401:客户端误触发重新登录。
- 403 响应提示「用户不存在」:辅助账号枚举。
追问
- 待确认:认证插件默认状态码映射,以文档核对。
- 接口同时可能 401/403 时怎么排?答:先确认主体是否取出,再看授权判定。
06.8.1.2-031 Basic 认证如何配置?
一句话结论
Basic provider 从 Authorization: Basic <base64> 解析用户名密码,调用校验函数比对凭据,成功产出 principal;配置 realm 标识;必须配合 HTTPS,否则凭据明文可被截获。
概念解释
Basic 是简单的传输编码而非加密:编码可被解码,安全性完全依赖传输加密。适合内部服务、调试或配合网关认证,不适合面向公网的浏览器会话。校验函数应使用安全的密码比对方式。
原理流程
- 安装 basic provider 并命名、设置 realm。
- 请求携带 Basic 头,provider 解码取出用户名密码。
- 校验函数核对凭据,成功构造 principal。
- 失败触发 challenge 返回 401 与协商头。
代码或图示
install(Authentication) {
basic("basic-auth") {
realm = "internal"
validate { credential ->
if (checkPassword(credential.name, credential.password))
UserPrincipal(credential.name, emptySet())
else null
}
}
}
常见误区
- HTTP 明文用 Basic:凭据被链路截获。
- 明文存密码或用普通字符串比对:应使用哈希与恒定时间比对。
追问
- 待确认:basic provider 配置项与凭据对象类型,以官方文档核对。
- Basic 适合浏览器长期登录吗?答:不适合,浏览器会缓存凭据,退出登录不可控。
06.8.1.2-032 Basic 认证有哪些安全注意事项?
一句话结论
必须走 HTTPS;密码用哈希存储与安全比对;凭据不进日志;设置合理 realm 与超时;公网场景优先 JWT/Session 方案;内部 Basic 也要限制来源网络。
概念解释
Basic 凭据每个请求都携带,被截获即可长期复用。注意点:传输加密、哈希校验、日志脱敏、网络隔离。不要把 Basic 当加密机制理解。
原理流程
- 确认全链路 HTTPS 终止位置与加密范围。
- 校验侧使用哈希与恒定时间比较。
- 日志输出剔除 Authorization 头。
- 网络层限制可访问来源。
代码或图示
安全清单:HTTPS / 密码哈希 / 日志脱敏 / 来源限制 / 方案适配场景
常见误区
- 认为 Base64 是加密:可被任意解码。
- 凭据出现在访问日志:泄露面扩大。
追问
- 密码哈希算法怎么选?答:按项目安全基线选用慢哈希算法,具体参数按安全规范。
- Basic 凭据能吊销吗?答:改密码或轮换密钥,没有独立会话状态可即时失效。
06.8.1.2-033 认证拦截如何挂到路由子树?
一句话结论
authenticate("provider-name") { ... } 块内注册的路由子树受该 provider 保护;块外路由保持公开;父块认证对子节点继承,新增子节点放在块内才受保护。
概念解释
认证挂载点决定保护边界。按业务域划分子树:公开接口在块外,受保护接口在块内。块内可再嵌套分组与额外授权拦截,结构清晰便于回归受保护面。
原理流程
- 安装命名 provider。
- 在 routing 内用 authenticate 块圈定子树。
- 子树请求先过认证 provider。
- 块外兄弟路由不受影响。
代码或图示
routing {
get("/health") { /* 公开 */ }
authenticate("jwt-auth") {
route("/me") { get { /* 受保护 */ } }
}
}
常见误区
- 新接口加在块外:漏保护。
- 认证块包过公开文档接口:被拦截无法访问。
追问
- 嵌套 authenticate 会叠加校验吗?答:按组合规则生效,具体行为见多认证题目。
- 节点级认证能继承到孙节点吗?答:块内子树继承。
06.8.1.2-034 authenticate 块内能否混合公开接口?
一句话结论
认证块默认保护块内全部路由;需要公开的特例应放到块外,或使用可选认证/匿名放行机制;把公开接口塞进受保护块再逐个放行,规则缠绕且容易遗漏。
概念解释
结构上应让认证边界与业务边界一致。少数匿名可访问的接口应在路由树中独立成公开分支。若框架支持可选认证,可在同一处理器内区分有无主体,但不要把强制保护与公开混写。
原理流程
- 划分强制认证与公开路由。
- 公开路由注册在认证块外。
- 需区分场景用可选认证。
- 回归两组路径断言状态码。
代码或图示
routing {
// 公开
get("/docs") { /* ... */ }
authenticate("jwt-auth") {
// 受保护
get("/profile") { /* ... */ }
}
}
常见误区
- 块内写例外判断:新增接口默认被保护,例外规则易漏。
- 可选认证被当成强制:匿名请求误进 Handler。
追问
- 待确认:可选认证在 Ktor 3 中的 provider 配置方式,以官方文档核对。
- 同一 URL 两种方法权限不同怎么办?答:按方法拆分节点分别挂载认证。
06.8.1.2-035 认证失败响应如何统一?
一句话结论
在 provider 的 challenge 或状态页层归一错误结构:401/403 状态码固定,body 使用统一错误码与中性消息;失败原因进日志,响应不暴露内部细节;多套认证方案输出同一格式。
概念解释
统一响应让客户端处理逻辑一致,网关统计状态码准确。归一位置选在认证 challenge 或 StatusPages,不要在每个 Handler 里写拒绝响应。消息区分可读的中性提示,细节留在服务端日志。
原理流程
- 定义统一错误响应结构。
- challenge 按失败类型填状态码与错误码。
- 日志记录具体原因与主体标识。
- 各 provider 复用同一归一出口。
代码或图示
// 失败响应结构示例;具体 challenge 入口以版本 API 为准
data class ApiError(val code: String, val message: String)
常见误区
- 不同 provider 返回不同错误格式:客户端分支混乱。
- 响应回显令牌错误细节:辅助伪造攻击分析。
追问
- 待确认:challenge 自定义响应体的配置方式,以官方文档核对。
- 限流拒绝与认证失败能同结构吗?答:状态码区分(401/403/429),body 结构可统一。
06.8.1.2-036 多个认证提供者如何组合?
一句话结论
同一认证块可引用多个 provider,按配置的选择策略依次尝试:任一通过即认证成功,全部失败触发 challenge;策略(全通过、任一通过)以版本 API 为准,未核对前标待确认。
概念解释
组合场景:同一接口同时接受 JWT 与内部 Basic,或多套令牌来源。多 provider 共用同一 principal 类型便于下游授权;不同类型主体需在读取时区分。组合顺序影响挑战响应的生成。
原理流程
- 在安装器内定义多个命名 provider。
- 认证块引用多个名称。
- 请求按策略逐个尝试校验。
- 通过则写主体,失败汇总触发 challenge。
代码或图示
authenticate("jwt-auth", "basic-auth") {
get("/admin") { /* ... */ }
}
常见误区
- 假设多 provider 一定是「任一通过」:策略需按配置确认。
- 不同 provider 产出不兼容主体类型:下游取值失败。
追问
- 待确认:Ktor 3 多 provider 组合策略(any/all)的配置入口,以官方文档核对。
- 部分成功部分失败如何响应?答:按策略与 challenge 配置,不泄露各 provider 细节。
06.8.1.2-037 可选认证如何实现?
一句话结论
可选认证表示:携带有效凭据则解析出主体,无凭据也放行进入 Handler;Handler 内判空主体区分匿名与登录态,不能把可选当成强制校验。具体 provider 配置方式以版本为准,标待确认。
概念解释
适用场景:公开接口可返回个性化增强内容,或同一处理器同时服务匿名与登录用户。可选认证不写主体时不触发拒绝 challenge;强制保护接口必须用普通认证块。
原理流程
- 配置可选 provider:凭据缺失不拒绝。
- 凭据有效解析主体写入 Call。
- Handler 读取可空主体分支处理。
- 凭据无效(非缺失)按策略决定拒绝还是忽略。
代码或图示
val principal = call.principal<UserPrincipal>()
if (principal != null) {
// 登录态逻辑
} else {
// 匿名逻辑
}
常见误区
- 可选认证块内接口仍假设主体非空:匿名请求空指针。
- 把非法令牌当匿名放行:应按安全策略判定无效凭据是否拒绝。
追问
- 待确认:Ktor 3 可选认证 provider 的 DSL 标志,以官方文档核对。
- 个性化缓存如何处理?答:匿名与登录响应分开缓存,避免串数据。
06.8.1.2-038 认证主体如何传进 Handler?
一句话结论
主体由认证 provider 写入 Call,Handler 用 call.principal<T>() 类型化取出;需要复用的字段可在 Handler 内转成参数或服务入参,不通过全局变量传递。
概念解释
传递链路:凭据 -> provider 校验 -> principal 对象 -> Call 上下文 -> Handler/授权层。类型化读取保证编译期检查;主体字段不可变,请求结束随 Call 释放。
原理流程
- provider 构造 principal 并写入。
- Handler 按类型读取。
- 授权层基于主体判定权限。
- 业务服务接收主体标识作为入参。
代码或图示
get("/me") {
val me = call.principal<UserPrincipal>() ?: return@get call.respond(HttpStatusCode.Unauthorized)
call.respond(mapOf("userId" to me.userId))
}
常见误区
- 把主体存到全局可变字段:并发串号。
- 在服务层再从请求头解析:绕过认证结果。
追问
- 主体能注入函数参数吗?答:可通过公共提取逻辑传入,Ktor 不强制注解注入。
- 多类型主体如何区分?答:按 provider 产出不同类型,分别 principal 读取。
06.8.1.2-039 认证插件与路由的安装顺序是什么关系?
一句话结论
Authentication 插件在应用层安装并注册 provider,路由块引用 provider 名称挂载到子树;插件先于路由引用配置,认证拦截在业务 Handler 之前生效;顺序颠倒或漏引用都会导致保护失效。
概念解释
安装分两步:先在 install(Authentication) 定义策略,再在路由中引用。管道层次上认证属于前置拦截,必须包裹业务节点。路由注册本身不依赖插件安装完成,但引用名称必须能解析到已注册 provider。
原理流程
- 模块装配期安装认证插件并定义 provider。
- 路由树注册受保护块并引用名称。
- 请求先过认证拦截,再进 Handler。
- 未通过 challenge 短路。
代码或图示
fun Application.module() {
install(Authentication) { jwt("jwt-auth") { /* ... */ } }
routing {
authenticate("jwt-auth") { get("/me") { /* ... */ } }
}
}
常见误区
- 路由引用了未定义的 provider 名称:启动或请求期行为异常,需测试暴露。
- 认证拦截装在业务之后:Handler 已执行。
追问
- 认证插件能在子模块单独安装吗?答:可以,但 provider 名称在同 Application 内需唯一可解析。
- 顺序问题怎么测?答:匿名请求枚举全部受保护路径断言 401/403。
06.8.1.2-040 Ktor 3 认证 API 有哪些需要核对的变化点?
一句话结论
升级时重点核对 provider DSL 名称、principal 读取方法、challenge 配置入口与多 provider 策略;具体移除/改名清单以官方迁移文档为准,未核实前标「待确认」,不凭记忆断言。
概念解释
认证是安全敏感模块,API 误用后果严重。核对路径:编译告警 -> 迁移指南 -> 官方认证文档 -> 测试验证。答案中应能说出需要核对的维度,而不是编造精确类名。
原理流程
- 编译收集弃用与 unresolved 告警。
- 对照迁移指南替换 provider 与主体读取写法。
- 回归匿名、无效、有效三类请求。
- 核对挑战响应与状态码行为。
代码或图示
核对清单:provider DSL / principal API / challenge 入口 / 组合策略 / 状态码映射
常见误区
- 把 2.x 认证笔记直接当 3.x 事实:安全模块行为可能已变。
- 编译通过即认为认证正确:仍需匿名请求回归。
追问
- 待确认:Ktor 3 认证相关弃用 API 列表,查官方 migration 文档逐条核对。
- 升级后优先观察什么?答:未认证请求是否被拒、主体是否正确取出、挑战响应格式。
06.8.1.2-041 JWT 认证在 Ktor 中如何接入?
一句话结论
安装 JWT provider:配置发行方、受众、密钥/公钥与校验规则,validate 回调把 Claims 映射为 principal;受保护路由引用该 provider,请求携带 Bearer 令牌进入校验。
概念解释
JWT provider 负责解析与验签,业务只消费 principal。令牌放在 Authorization Bearer 头是常见形式;校验规则覆盖签名、过期、发行方、受众等声明。接入前先确认使用的 JWT 库与 Ktor 版本兼容。
原理流程
- 安装 JWT 插件并配置校验参数。
- validate 回调读取 Claims 构造主体。
- 路由块引用 JWT provider。
- 请求携带令牌,provider 验签通过后放行。
代码或图示
install(Authentication) {
jwt("jwt-auth") {
// 配置验证器:密钥/公钥、issuer、audience 等
validate { credential ->
UserPrincipal(credential.payload.getSubject())
}
}
}
常见误区
- 只解码不验签:令牌可被伪造。
- validate 内做远程调用阻塞:认证阶段拖慢管道。
追问
- 待确认:Ktor 3 JWT 插件坐标与配置对象字段,以官方文档核对。
- 令牌从哪里取?答:默认 Authorization Bearer,自定义取令牌方式按插件能力配置。
06.8.1.2-042 JWT 验签需要校验哪些要素?
一句话结论
先验签名保证完整性,再校验过期时间、发行方、受众与必要声明;算法白名单固定,密钥匹配;任何一项不通过即拒绝,不要只看 payload 能解码就放行。
概念解释
签名防止内容被篡改;过期控制时效;issuer/audience 限定令牌适用系统与对象;必要声明(角色、租户)满足接口要求。校验全部在信任边界内完成,失败统一走 challenge。
原理流程
- 提取并解析令牌结构。
- 用匹配密钥/公钥验证签名。
- 校验 exp、iss、aud 与自定义声明。
- 通过后映射 principal,否则拒绝。
代码或图示
校验顺序:签名 -> exp -> iss -> aud -> 自定义声明 -> 主体映射
常见误区
- 不校验 iss/aud:别的系统签发的令牌可复用。
- 过期容忍时间不明确:时钟漂移与撤销窗口处理混乱。
追问
- 时钟漂移怎么处理?答:配置有限的过期容忍窗口,具体值按安全基线。
- 声明缺失算什么失败?答:按未认证或无权限处理,不进入业务。
06.8.1.2-043 JWT 密钥与算法如何配置?
一句话结论
对称算法用共享密钥,非对称算法用公钥验签(私钥仅在签发侧);算法固定在白名单,不接受令牌头指定的任意算法;密钥按环境隔离并支持轮换,不写进代码仓库。
概念解释
HS256 等对称算法验签与签发共用密钥,泄露即可伪造;RS256 等非对称算法服务端只持公钥。算法混淆攻击利用头声明改算法类型,因此服务端强制配置算法而非信任令牌头。
原理流程
- 选定算法与密钥类型。
- 服务端配置验签密钥/公钥。
- 固定允许的算法白名单。
- 密钥经环境变量/密钥管理注入,支持轮换。
代码或图示
对称:密钥两端共享,保管要求高
非对称:服务端持公钥验签,私钥隔离在签发侧
常见误区
- 允许
alg: none或任意算法:签名校验可被绕过。 - 密钥硬编码进配置仓库:泄露后无法快速轮换。
追问
- 待确认:JWT 验证器密钥与算法配置字段,以插件文档核对。
- 密钥轮换怎么做?答:过渡期双密钥验签,新签发用新密钥,旧密钥逐步下线。
06.8.1.2-044 Claims 如何映射为 principal?
一句话结论
validate 回调从已验签的 payload 读取 subject、角色、租户等声明,构造类型化 principal;读取缺失声明时返回 null 拒绝认证;主体不保留原始令牌与敏感明文。
概念解释
映射是 JWT 到应用身份模型的转换层:声明名与应用主体字段对应。转换失败(声明缺失、格式非法)按认证失败处理。principal 携带授权所需的最小信息集。
原理流程
- 验签通过后进入 validate。
- 读取标准与自定义声明。
- 校验必要声明存在并构造主体。
- 失败返回 null,触发 challenge。
代码或图示
validate { credential ->
val sub = credential.payload.subject ?: return@validate null
val roles = credential.payload.getClaim("roles").asList(String::class.java)
UserPrincipal(sub, roles.toSet())
}
常见误区
- 把整段 payload 塞进 principal:冗余且可能含敏感声明。
- 声明类型不校验直接用:解析异常变成 500。
追问
- 待确认:Claim 取值 API(asString/asList 等)在所用 JWT 库中的方法名,以库文档核对。
- 角色声明过期怎么办?答:令牌有效期内角色不变,权限变更需重新签发或走服务端授权。
06.8.1.2-045 JWT 过期与刷新如何处理?
一句话结论
访问令牌短时效,过期返回 401;刷新令牌换取新访问令牌,刷新本身也有生命周期与失效控制;服务端不保存访问令牌状态,但刷新令牌可在服务端管理与撤销。
概念解释
无状态令牌缩短泄露后的可用窗口;刷新机制平衡体验与安全。刷新令牌存储于服务端或受控 Cookie,可单独吊销。前端处理 401 时走刷新流程,刷新失败再重新登录。
原理流程
- 访问令牌过期,provider 拒绝并返回 401。
- 客户端用刷新令牌调用刷新接口。
- 服务端校验刷新令牌,签发新访问令牌。
- 刷新令牌轮换或失效后要求重新登录。
代码或图示
访问令牌(短时效,无状态)
刷新令牌(可吊销,服务端记录或受控存储)
常见误区
- 访问令牌设很长有效期:泄露后长期可用。
- 刷新令牌不过期、不可吊销:泄露后无法收回。
追问
- 待确认:所用 JWT 库与 Ktor 插件对过期令牌的异常/响应处理,以文档核对。
- 多端登录刷新如何管理?答:按设备/会话记录刷新令牌,支持单点吊销。
06.8.1.2-046 JWT 撤销与黑名单怎么做?
一句话结论
无状态 JWT 本身无法主动失效;需要撤销时引入黑名单(登出、改密、强制下线的令牌标识存入缓存并设剩余有效期),或缩短访问令牌有效期配合刷新令牌吊销;黑名单查询在认证阶段完成。
概念解释
撤销场景:用户登出、密码变更、权限回收、安全下线。黑名单记录 jti 或用户会话标识,TTL 不超过令牌剩余有效期,避免无限增长。高并发下黑名单存储需低延迟,命中即拒绝。
原理流程
- 登出/下线时把令牌 jti 或会话标识写入黑名单。
- 认证校验签名与声明后,查黑名单。
- 命中拒绝,否则放行。
- 条目随令牌过期自动清除。
代码或图示
// 伪流程:验签通过后检查黑名单
if (blacklist.contains(jti)) return@validate null
常见误区
- 认为 JWT 登出即失效:客户端删令牌,服务端无状态,令牌在过期前仍可用。
- 黑名单永久保存:存储膨胀。
追问
- 黑名单存哪里?答:Redis 等低延迟缓存,按 TTL 清理;规模与可用性按部署评估。
- 待确认:Ktor 认证阶段接入远程黑名单的位置与阻塞约束,以实现核对。
06.8.1.2-047 不验签直接读 payload 有什么风险?
一句话结论
未验签的 payload 可被任意伪造:攻击者篡改 subject、角色等声明冒充身份;Base64 解码不等于校验,任何把解码内容当可信身份的做法都是严重漏洞。
概念解释
JWT 三段中签名只防篡改,payload 本身可读。信任决策(用户是谁、有无权限)必须建立在验签通过之后。调试时解码 payload 看内容可以,业务认证绝不能走解码直读。
原理流程
- 攻击者修改 payload 中身份/角色声明。
- 重新编码但不补有效签名(或用 none 算法)。
- 服务端若直读 payload 即信任伪造内容。
- 越权或冒充身份成功。
代码或图示
错误:decode(payload) -> 取 userId -> 放行
正确:verify(签名) -> 校验声明 -> 映射主体
常见误区
- 以为 payload 加密了:实际只是编码。
- 调试代码残留在生产认证路径:伪造入口。
追问
- 如何代码审计发现这类问题?答:搜索令牌解码调用点,确认其下游没有做验签与身份决策。
- 待确认:所用 JWT 库是否分离解码与验签 API,以库文档核对。
06.8.1.2-048 算法混淆攻击如何防范?
一句话结论
服务端固定允许的签名算法白名单,不信任令牌头中的 alg;非对称场景不把公钥当对称密钥使用;验签配置明确算法,库默认拒绝 none 算法。
概念解释
算法混淆诱导服务端用错误密钥或算法验证签名(如把 RS256 当 HS256,用公钥当 HMAC 密钥)。防御核心:算法由服务端配置决定,密钥类型与算法匹配,库配置关闭不安全算法。
原理流程
- 服务端配置固定算法与对应密钥。
- 验签按配置算法执行,忽略令牌头算法声明。
- 密钥类型与算法一致。
- 未知/拒绝算法直接失败。
代码或图示
服务端配置:alg = RS256,验签公钥
令牌头 alg 仅作参考,不改变服务端策略
常见误区
- 按令牌头 alg 选择验签方式:策略被攻击者控制。
- 非对称公钥误用于 HMAC 校验:密钥材料泄露面被滥用。
追问
- 待确认:JWT 库是否默认限制算法列表,以库安全文档核对。
- 多算法兼容期怎么过渡?答:按系统约定逐步收敛到单一算法。
06.8.1.2-049 JWT 放在请求头还是 Cookie?
一句话结论
API 调用常用 Authorization Bearer 头,由前端代码主动携带;浏览器站点可用 HttpOnly Cookie 存储令牌防 XSS 窃取;两种方式各有风险面,选择按调用形态与防护能力决定。
概念解释
Bearer 头不受 Cookie 自动携带影响,适合 SPA 与开放 API;Cookie 方式减少 JS 读取令牌的暴露面,但需防 CSRF。令牌存放位置还要配合传输加密、过期策略与存储安全。
原理流程
- 调用形态:前后端分离 API -> 头;浏览器站点 -> Cookie。
- Cookie 设 HttpOnly、Secure、SameSite。
- 传输全程 HTTPS。
- 令牌有效期与刷新策略配套。
代码或图示
Bearer 头:前端主动附加,适合 API/跨端
Cookie:HttpOnly 防脚本读取,需 CSRF 防护
常见误区
- JS 可读的 localStorage 令牌配合 XSS 面:令牌易被盗。
- Cookie 不设 SameSite:跨站请求可自动携带。
追问
- 待确认:Ktor 对 Cookie 令牌的读取支持方式,以会话/认证文档核对。
- 开放第三方调用用哪种?答:Bearer 头或签名方案,避免 Cookie 自动携带语义。
06.8.1.2-050 令牌携带与 CORS 凭据如何配合?
一句话结论
跨域请求携带 Cookie 凭据时,CORS 配置允许凭据来源(不能用通配符 * 放行来源);Bearer 头方式需在允许头列表中包含 Authorization;预检通过后浏览器才发送凭据与自定义头。
概念解释
CORS 约束跨域读取与凭据携带:来源精确匹配、允许方法与头、允许凭据三者配套。自定义头(Authorization、自定义业务头)要在预检响应中声明允许,否则浏览器拦截。
原理流程
- 服务端配置允许来源(精确域,非通配)。
- 声明允许方法与请求头。
- 凭据模式开启时配置对应标志。
- 浏览器预检通过后发实际请求。
代码或图示
install(CORS) {
// 来源精确配置;allowCredentials 与来源规则以插件文档为准
anyMethod()
header("Authorization")
}
常见误区
- 凭据模式下来源用
*:浏览器拒绝携带凭据。 - 漏加允许头:Authorization 在预检后被拦截。
追问
- 待确认:Ktor CORS 插件凭据配置项名称,以官方文档核对。
- 跨域 Cookie 还要注意什么?答:SameSite、Domain、Path 属性与站点方案匹配。
06.8.1.2-051 多租户/多受众 JWT 如何校验?
一句话结论
令牌声明中携带租户或受众标识,接口校验当前请求匹配的租户/受众;多租户系统还要在授权与数据查询层按租户隔离,不能只靠令牌声明信任数据归属。
概念解释
audience 限定令牌适用的 API 系统,tenant 限定所属租户。校验在认证阶段完成声明匹配,数据层按租户条件过滤。租户标识从已验签主体取,不接受请求参数覆盖。
原理流程
- 令牌签发时带 aud 与 tenant 声明。
- 认证 provider 校验 aud/tenant 与当前服务匹配。
- principal 携带租户标识。
- 业务查询按租户隔离条件过滤。
代码或图示
// 校验示意:声明匹配当前租户
if (principal.tenant != currentTenant) {
call.respond(HttpStatusCode.Forbidden)
}
常见误区
- 用请求头/参数传租户覆盖令牌声明:越权跨租户。
- 认证过了就不做数据层隔离:水平越权。
追问
- 多租户令牌跨服务复用吗?答:audience 限定服务范围,跨服务需重新签发或明确信任关系。
- 待确认:Claim 中租户字段的类型与缺失处理,以实现核对。
06.8.1.2-052 JWT 插件的坐标与配置项需要核对哪些点?
一句话结论
接入前核对:插件/库 Maven 坐标与 Ktor、Kotlin 版本兼容,验证器配置字段(密钥、算法、issuer、audience、过期容忍),主体回调签名;不确定坐标标待确认并查官方文档与依赖仓库。
概念解释
版本不兼容会出现编译告警或运行期验签异常。核对清单包括依赖坐标、配置对象属性名、回调入参类型、异常类型。不要在答案里编造未核实的版本号与坐标。
原理流程
- 查官方文档确认 JWT 方案与依赖坐标。
- 对齐 Ktor/Kotlin 基线版本。
- 逐字段核对验证器配置。
- 用有效、过期、伪造令牌三类用例验证。
代码或图示
核对清单:依赖坐标 / 版本兼容 / 验证器字段 / 回调签名 / 异常类型
常见误区
- 凭记忆写坐标:版本与库名可能已变。
- 只测有效令牌:过期与伪造路径未验证。
追问
- 待确认:Ktor 3 JWT 插件确切坐标与配置属性,以 ktor.io 文档与依赖仓库为准。
- 验签失败抛什么异常?答:以库实现为准,认证插件转换为 challenge 响应。
06.8.1.2-053 Session 认证模型与 JWT 有什么区别?
一句话结论
Session 在服务端保存会话状态,客户端只持有会话标识;JWT 自包含声明,服务端不保存会话状态。Session 可即时吊销,JWT 撤销依赖黑名单或短时效;选型看会话管理需求与部署形态。
概念解释
Session 标识(Session ID)本身无意义,状态在服务端;令牌载荷可被客户端解码。Session 适合传统浏览器与需要主动下线的场景,JWT 适合开放 API 与跨服务无状态传递。两者都依赖 HTTPS 保护凭据。
原理流程
- 登录成功服务端创建会话,返回会话标识。
- 后续请求携带标识,服务端查会话状态。
- 会话可主动删除/失效。
- 对比 JWT:声明在令牌内,服务端验签后信任。
代码或图示
Session:ID -> 服务端存储(可吊销)
JWT:自包含声明 -> 验签信任(撤销需配套机制)
常见误区
- 把 Session ID 当令牌信任内容:状态以服务端存储为准。
- 认为无状态就完全不需要撤销:泄露令牌仍需限制影响。
追问
- 待确认:Ktor Session 插件的存储与 Cookie 配置 API,以官方文档核对。
- 混合方案可行吗?答:可在服务端会话基础上加短期访问令牌,按场景组合。
06.8.1.2-054 服务端 Session 如何存储?
一句话结论
会话数据存服务端存储(内存、Redis 或数据库),客户端只持标识;多实例部署用共享存储,内存存储仅适合单实例;存储设过期、淘汰与序列化兼容策略。
概念解释
内存会话重启即失且不能多实例共享;Redis 等共享存储支持集群与会话过期。会话数据最小化:只存必要标识与引用,敏感信息不进会话体。存储访问需低延迟,认证阶段同步读取要控制超时。
原理流程
- 登录创建会话,生成标识。
- 会话数据写入存储并设 TTL。
- 请求携带标识,存储读取会话。
- 登出或过期清除会话。
代码或图示
单实例:内存 Map(重启丢失)
多实例:共享缓存/数据库(按标识读写,带 TTL)
常见误区
- 多实例用内存会话:请求落到不同实例状态丢失。
- 会话体存大对象:存储与读取成本上升。
追问
- 待确认:Ktor Session 插件是否提供服务端会话存储适配器,以文档核对;多数场景需自接共享存储。
- 会话存储故障怎么办?答:降级策略与超时控制,避免认证阶段阻塞。
06.8.1.2-055 Cookie Session 的安全属性有哪些?
一句话结论
会话 Cookie 设 HttpOnly 防脚本读取、Secure 限 HTTPS、SameSite 防跨站自动携带,Path/Domain 收敛作用域;标识不可预测,过期与滑动策略明确;敏感会话不通过 URL 传递。
概念解释
Cookie 属性决定泄露与滥用面:HttpOnly 降低 XSS 窃取风险,Secure 防明文传输,SameSite 缓解 CSRF。会话标识需高熵随机,不能自包含可解码信息。Cookie 名称与作用域按站点约定收敛。
原理流程
- 登录成功下发会话 Cookie。
- 设置安全属性与作用域。
- 浏览器后续请求自动携带。
- 登出清除 Cookie 与服务端会话。
代码或图示
Cookie 属性:HttpOnly / Secure / SameSite / Path / Domain / Max-Age
常见误区
- 会话标识放 URL 参数:进日志与历史记录。
- 不设 SameSite:跨站请求自动携带触发 CSRF。
追问
- 待确认:Ktor Session Cookie 属性配置方式,以官方文档核对。
- 跨子域共享会话怎么设 Domain?答:按最小必要范围配置,避免过宽 Domain。
06.8.1.2-056 Session 过期与滑动过期如何处理?
一句话结论
绝对过期限制会话最大生命周期;滑动过期在活动时续期,但总时长有上限;空闲超时清除不活动会话;两类策略在存储 TTL 与 Cookie Max-Age 上保持一致。
概念解释
滑动过期提升体验但长期不活动仍应登出。续期动作应更新服务端存储 TTL 与 Cookie 过期时间;敏感操作可要求重新认证。策略不一致会出现 Cookie 有效但服务端会话已清除的情况。
原理流程
- 登录设定绝对有效期。
- 活动请求时按滑动策略续期。
- 空闲超过阈值清除会话。
- 存储与 Cookie 过期时间同步更新。
代码或图示
绝对上限:最长会话时长
滑动续期:每次活动延长,但不超过上限
空闲超时:无活动即失效
常见误区
- 只续 Cookie 不续服务端 TTL:会话中途消失。
- 滑动无限续期:被盗会话长期有效。
追问
- 待确认:Ktor Session 插件是否内置滑动过期支持,以文档核对;否则在拦截层续期。
- 敏感操作重认证怎么做?答:记录最近认证时间,超阈值要求重新登录。
06.8.1.2-057 会话固定攻击如何防范?
一句话结论
登录成功后重新生成会话标识,废弃登录前的匿名标识;标识高熵随机;登出与权限变更时轮换标识;不接受客户端预设的会话 ID。
概念解释
会话固定是攻击者预置或获取一个会话 ID,待受害者登录后复用该标识提权。防御关键是认证状态变化时标识轮换:匿名 -> 登录、普通 -> 提权都换新 ID,旧 ID 失效。
原理流程
- 匿名阶段标识仅用于临时状态。
- 登录成功生成新标识,迁移必要会话数据。
- 旧标识作废。
- 提权/改密再次轮换。
代码或图示
登录前 ID -> 登录成功:换新 ID,旧 ID 失效
常见误区
- 登录前后使用同一 ID:攻击者预置 ID 即可复用。
- 标识可预测:被枚举或猜测。
追问
- 待确认:Ktor Session 插件是否支持标识轮换 API,以文档核对;否则在登录流程重建会话。
- 会话数据迁移怎么办?答:新会话复制必要数据,旧会话删除。
06.8.1.2-058 分布式部署下 Session 如何共享?
一句话结论
会话状态存入多实例可访问的共享存储(Redis 等),实例只保留标识解析能力;会话复制需考虑一致性、过期与故障降级;不要用各实例内存会话拼凑分布式状态。
概念解释
共享存储解决实例间会话可见性。读写延迟影响认证响应,需超时与降级策略;会话序列化要兼容版本演进。会话粘滞可作为过渡,但不替代共享存储,实例重启仍丢状态。
原理流程
- 会话写入共享存储并设 TTL。
- 任意实例读取标识对应会话。
- 更新会话回写存储。
- 存储故障按降级策略处理。
代码或图示
实例 A/B/C -> 共享会话存储(Redis)
常见误区
- 靠会话粘滞规避共享存储:扩容重启仍丢状态。
- 会话对象直接序列化进不兼容格式:版本升级后反序列化失败。
追问
- 待确认:共享存储适配器与序列化方式,按所选库实现核对。
- 会话读取超时怎么办?答:有限超时,失败按未认证或降级策略,不无限阻塞。
06.8.1.2-059 Session 序列化有哪些注意事项?
一句话结论
会话对象字段稳定、类型明确,避免序列化不兼容的复杂对象;版本演进时字段增删保持兼容;敏感数据不进会话体;跨语言共享存储时选用通用编码格式。
概念解释
会话在重启、扩容、版本升级后仍需可读取。序列化失败表现为登录态丢失或反序列化异常。会话体应是简单数据结构,引用的服务对象不应直接存入会话。
原理流程
- 定义简单会话数据类。
- 字段变更保持向后兼容。
- 序列化格式与存储匹配。
- 升级前验证旧会话可读取或明确清除策略。
代码或图示
data class SessionState(val userId: String, val issuedAt: Long)
常见误区
- 把业务实体引用存会话:生命周期与序列化双重问题。
- 字段类型直接改窄/改删:旧会话反序列化失败。
追问
- 待确认:Ktor Session 插件默认序列化方式与可替换编码器,以文档核对。
- 旧版本会话如何处理?答:升级时清除或做兼容反序列化,按发布策略决定。
06.8.1.2-060 什么时候选 Session,什么时候选 Token?
一句话结论
传统浏览器站点、需要即时吊销与集中会话管理选 Session;开放 API、跨服务传递、无状态部署选 Token;按客户端形态、撤销需求、生态集成与团队经验综合决策,可混合使用。
概念解释
决策维度:客户端能否安全存 Cookie、撤销时效要求、多服务信任关系、部署无状态程度。Session 服务端有状态,Token 依赖有效期与配套撤销机制。没有绝对优劣,匹配场景即可。
原理流程
- 梳理客户端形态与凭据存储能力。
- 确认撤销与多端管理需求。
- 评估服务端状态与部署模型。
- 选定方案并配套防护措施。
代码或图示
Session:浏览器、即时下线、集中管理
Token:开放 API、跨服务、无状态节点
常见误区
- 因为「无状态潮流」在浏览器站点硬上 Token:防护与刷新复杂化。
- 开放 API 用服务端 Session:跨端传递与扩展不便。
追问
- 待确认:项目现有认证体系以 06.8.2 Spring Boot 章节为准,本节不展开重复。
- 混合架构怎么切?答:边缘会话控制访问,内部服务用短期令牌传递身份。
06.8.1.2-061 ContentNegotiation 插件的职责是什么?
一句话结论
ContentNegotiation 按请求与响应的 Content-Type 选择序列化/反序列化转换器:请求体反序列化为对象,响应对象序列化为 body 并设置正确 Content-Type;未匹配转换器时按失败处理。
概念解释
插件把 Handler 从手动读写 JSON/表单中解放出来:call.receive<T>() 与 call.respond(obj) 走协商管线。转换器按内容类型注册,序列化库(kotlinx.serialization、Jackson)通过转换器接入。
原理流程
- 安装插件并注册各类型转换器。
- 请求进入:按 Content-Type 选反序列化器读取 body。
- Handler 操作类型化对象。
- 响应:按 Accept 或对象类型选序列化器写出并设头。
代码或图示
install(ContentNegotiation) {
json(Json { ignoreUnknownKeys = true })
}
常见误区
- 未安装插件直接 receive 对象:类型转换无人处理。
- 转换器只注册了响应方向:请求反序列化失败。
追问
- 待确认:Ktor 3 ContentNegotiation 转换器注册 API,以官方文档核对。
- 文本响应需要转换器吗?答:纯文本由基础响应能力处理,对象 JSON 才走协商。
06.8.1.2-062 Accept 与 Content-Type 如何参与匹配?
一句话结论
请求 Content-Type 标识发来 body 的格式,决定反序列化器;Accept 标识期望的响应格式,决定序列化器;协商不到支持的类型时按不支持处理(406 或按默认格式),具体行为以引擎实现为准。
概念解释
两个头方向不同:入参看 Content-Type,出参看 Accept。转换器注册时绑定媒体类型。客户端未带 Accept 时按默认转换器响应;服务端不支持期望类型应明确失败,而不是偷偷换格式。
原理流程
- 读取请求 Content-Type 匹配反序列化转换器。
- 读取 Accept 列表匹配响应序列化器。
- 匹配成功走对应编解码。
- 无匹配:返回不支持类型或默认行为。
代码或图示
请求:Content-Type: application/json -> JSON 反序列化
响应:Accept: application/json -> JSON 序列化
常见误区
- 混淆两个头方向:以为 Accept 决定请求解析。
- 忽略不匹配场景:客户端拿到无法解析的格式。
追问
- 待确认:Ktor 3 对不支持 Accept 的默认响应状态,以文档核对。
- 同一接口多格式输出怎么配?答:注册多转换器,按 Accept 协商。
06.8.1.2-063 kotlinx.serialization 如何接入?
一句话结论
注册 JSON 转换器并配置 Json 实例;数据类标注 @Serializable,序列化插件按 Kotlin 反射/编译期元数据编解码;接入需引入对应序列化依赖,版本与 Kotlin 基线匹配。
概念解释
kotlinx.serialization 是 Kotlin 原生序列化方案,配合编译期插件生成序列化器。配置项覆盖未知键忽略、默认值编码、命名策略、宽松解析等。数据类与枚举需可序列化,第三方类型需自定义序列化器。
原理流程
- 引入序列化依赖并对齐 Kotlin 版本。
- 配置 Json 实例。
- 安装 ContentNegotiation 注册 json 转换器。
- 数据类标注后 receive/respond 自动编解码。
代码或图示
@Serializable
data class UserDto(val id: Int, val name: String)
install(ContentNegotiation) {
json(Json { ignoreUnknownKeys = true })
}
常见误区
- 数据类漏标
@Serializable:编译期或运行期找不到序列化器。 - Json 配置两侧不一致:客户端与服务端解析行为差异。
追问
- 待确认:Ktor 3 kotlinx.serialization 转换器依赖坐标,以官方文档核对。
- 自定义类型怎么处理?答:写自定义 KSerializer 并注册。
06.8.1.2-064 Jackson 如何接入?与 kotlinx.serialization 怎么选?
一句话结论
Jackson 通过 ObjectMapper 接入 JSON 转换器,适合已有 Java/Jackson 生态与注解体系;kotlinx.serialization 更贴近 Kotlin 原生与多平台;选型看既有依赖、注解习惯与是否需要多平台,不重复装配两套。
概念解释
Jackson 成熟、生态大、模块丰富;kotlinx 轻量、编译期生成、Kotlin 语义贴合。同一服务通常选一套 JSON 方案,避免双序列化依赖与配置漂移。Kotlin 数据类在 Jackson 下需模块支持处理默认值与空值。
原理流程
- 评估既有生态与依赖体积。
- 选定方案并配置映射规则。
- 注册对应转换器。
- 统一 DTO 风格与配置。
代码或图示
install(ContentNegotiation) {
jackson {
// ObjectMapper 配置:命名策略、日期、空值等
}
}
常见误区
- 同一服务同时挂两套 JSON 转换器:行为不确定且依赖膨胀。
- Jackson 未注册 Kotlin 模块:数据类构造与默认值解析异常。
追问
- 待确认:Ktor 3 Jackson 转换器依赖与 ObjectMapper 配置入口,以文档核对。
- 多平台项目倾向哪个?答:kotlinx.serialization 多平台支持更自然,按目标平台评估。
06.8.1.2-065 序列化配置有哪些常见项?
一句话结论
常见配置:忽略未知键、是否编码默认值、空值处理、日期/时间格式、命名策略、枚举大小写、宽松数字解析;配置在客户端与服务端之间保持一致,避免字段丢失或解析失败。
概念解释
忽略未知键提升前后端版本兼容;默认值编码影响报文大小;日期格式需统一时区与格式。配置项按所选序列化库 API 落地,不要假设两套库配置同名。
原理流程
- 确定兼容策略:未知字段、默认值、空值。
- 配置时间与命名约定。
- 与客户端/其他服务对齐。
- 用样例报文验证往返一致。
代码或图示
Json {
ignoreUnknownKeys = true
encodeDefaults = false
}
常见误区
- 严格拒绝未知字段:接口演进时旧客户端被拒。
- 日期默认格式不统一:跨服务解析偏差。
追问
- 待确认:各配置项在 kotlinx/Jackson 中的准确属性名,以库文档核对。
- 枚举前端传字符串怎么配?答:按库配置枚举读取策略,校验非法值。
06.8.1.2-066 请求反序列化失败如何处理?
一句话结论
body 格式错误、字段缺失或类型不符属于客户端错误,应映射 400 与统一错误结构;异常在插件或 StatusPages 层捕获,记录报文特征(不含敏感内容),不把解析堆栈返回给客户端。
概念解释
反序列化异常分语法错误与语义错误:JSON 不合法、类型不匹配、必填缺失。失败响应指出字段与原因有助于客户端修正,但不暴露内部类名与堆栈。配置上可放宽未知键,必填与类型仍严格校验。
原理流程
- 转换器反序列化抛出异常。
- 异常进入状态页/插件处理器。
- 映射 400 与字段级错误信息。
- 日志记录异常与 trace 标识。
代码或图示
install(StatusPages) {
// 捕获反序列化异常,返回 400 统一结构;异常类型以所用库为准
}
常见误区
- 解析异常变成 500:客户端错误被当系统故障。
- 响应回显完整堆栈与类名:泄露内部结构。
追问
- 待确认:反序列化异常的具体类型层次,以序列化库实现核对。
- 字段级错误列表怎么返回?答:在错误结构中带字段与原因,按 API 约定。
06.8.1.2-067 响应序列化失败如何处理?
一句话结论
响应对象存在不可序列化字段、循环引用或类型不支持时,序列化在写出阶段失败;应在测试中覆盖响应 DTO 可序列化,失败兜底 500 并记录,响应不被客户端看到残缺 body。
概念解释
响应序列化问题多为 DTO 设计:暴露不可序列化类型、双向关联循环引用、日期类型未配置。发布前用样例对象走一遍序列化;运行期失败要保证响应状态与 body 不矛盾。
原理流程
- Handler 产出响应对象。
- 转换器序列化时发现不支持结构。
- 异常被兜底处理,记录对象类型与字段。
- 返回中性错误响应。
代码或图示
预防:DTO 只用基础类型与可序列化数据类,关联关系扁平化
常见误区
- 直接把领域实体当响应 DTO:内部结构与循环引用外泄。
- 序列化失败后仍声称 200:body 残缺或为空。
追问
- 待确认:写出阶段序列化异常的捕获时机,以插件实现核对。
- 循环引用怎么避免?答:响应 DTO 单向扁平化,不返回实体图。
06.8.1.2-068 自定义 Converter 如何注册?
一句话结论
实现对应媒体类型的编解码契约,在 ContentNegotiation 安装时按类型注册;用于非 JSON 格式(表单、自定义文本、二进制)或需要定制编解码规则的场景;注册后 receive/respond 按类型选用。
概念解释
转换器负责对象与报文之间的双向映射:反序列化读字节构造对象,序列化写对象写字节与媒体类型。自定义转换器要处理空 body、非法格式与异常抛出规则,与框架异常处理衔接。
原理流程
- 定义转换器实现编解码接口。
- 指定支持的媒体类型。
- install 时注册到协商插件。
- 请求/响应按媒体类型匹配调用。
代码或图示
Converter:
- read(contentType, body): 对象
- write(contentType, obj): body + 头
常见误区
- 只实现一个方向:另一方向无人处理。
- 自定义编解码不抛规范异常:错误状态难以映射。
追问
- 待确认:Ktor 3 转换器接口与注册方法签名,以官方文档核对。
- 多版本格式共存怎么办?答:按媒体类型区分转换器,版本协商在类型上表达。
06.8.1.2-069 文本、HTML、二进制响应与内容协商是什么关系?
一句话结论
纯文本/HTML 由 respondText、respondBytes 等基础能力直接写出并设置媒体类型,不经过对象 JSON 转换器;内容协商主要针对结构化对象编解码;二进制下载要正确设置 Content-Type 与长度/流式策略。
概念解释
区分响应形态:字符串与字节直接响应,对象才序列化。HTML 模板渲染、文件下载、字节流各走对应响应 API。媒体类型错误会导致客户端解析行为异常(下载变成展示等)。
原理流程
- 判断响应形态:文本/字节/结构化对象。
- 文本与字节用基础响应 API。
- 对象走协商转换器。
- 设置正确 Content-Type 与必要头。
代码或图示
call.respondText("<html>...</html", ContentType.Text.Html)
call.respondBytes(bytes, ContentType.Application.OctetStream)
常见误区
- JSON 对象当字符串拼接:绕过序列化与转义。
- 二进制下载不设类型:浏览器按默认方式处理。
追问
- 待确认:响应 API 与媒体类型常量在 Ktor 3 中的名称,以文档核对。
- HTML 输出如何防 XSS?答:模板转义或输出编码,见安全题目。
06.8.1.2-070 序列化插件的坐标与版本基线需要核对哪些点?
一句话结论
核对转换器依赖坐标、与 Ktor 3/Kotlin 2.x 的版本兼容、序列化库自身版本;kotlinx 序列化需匹配 Kotlin 编译器插件版本;不确定坐标与版本标待确认,以官方文档和依赖仓库为准。
概念解释
版本错配会出现编译报错、运行期找不到序列化器或行为差异。核对矩阵:Ktor 版本、Kotlin 版本、序列化库版本、Jackson 模块版本。项目内统一版本管理,不各处引入不同大版本。
原理流程
- 对齐 Ktor 与 Kotlin 基线。
- 查官方文档确认转换器坐标。
- 锁定序列化库兼容版本。
- 用往返报文测试验证。
代码或图示
核对矩阵:Ktor / Kotlin / kotlinx-serialization 或 Jackson 模块版本
常见误区
- 凭记忆写依赖版本:与基线不兼容。
- 服务端与客户端序列化库版本差距过大:格式细节不一致。
追问
- 待确认:Ktor 3 各序列化转换器的确切坐标与推荐版本,以 ktor.io 文档为准。
- 升级序列化库先测什么?答:往返兼容、默认值与空值、日期格式。
06.8.1.2-071 CORS 插件解决什么问题?
一句话结论
CORS 插件按浏览器跨域规则附加响应头,声明允许的来源、方法、头与凭据;它只管理浏览器侧跨域限制,不替代服务端认证与网络层访问控制。
概念解释
浏览器出于同源策略限制跨域读取,服务端通过 CORS 响应头告知浏览器哪些跨域调用被允许。预检请求(OPTIONS)与实际请求分别处理。CORS 放行不等于信任调用方,认证仍需独立完成。
原理流程
- 浏览器发起跨域请求或预检。
- 插件匹配来源与请求方法/头。
- 追加 CORS 响应头。
- 浏览器据此决定是否放行脚本读取响应。
代码或图示
install(CORS) {
anyMethod()
header("Authorization")
// 来源按精确域配置
}
常见误区
- 把 CORS 当鉴权:放通来源后仍需认证。
- 公网服务随意允许所有来源:扩大跨域滥用面。
追问
- 待确认:Ktor 3 CORS 插件配置项名称,以官方文档核对。
- 非浏览器调用受 CORS 约束吗?答:不受浏览器策略约束,仍按服务端安全规则控制。
06.8.1.2-072 允许来源、方法、头如何配置?
一句话结论
来源用精确域名列表或匹配规则配置,方法按需枚举,请求头与暴露头分别声明;不要在凭据模式下用通配来源;配置最小必要集合,定期复审。
概念解释
允许方法控制跨域可调用的 HTTP 动词;允许请求头决定预检可携带的自定义头;暴露头决定脚本可读的响应头。配置过宽等于放松浏览器侧限制,收窄到业务所需范围。
原理流程
- 列出前端站点来源清单。
- 枚举接口使用的方法。
- 声明自定义请求头与需暴露的响应头。
- 按环境区分开发与生产配置。
代码或图示
Allow-Origin: 精确来源列表
Allow-Methods: GET, POST, ...
Allow-Headers: Authorization, Content-Type
Expose-Headers: 自定义响应头
常见误区
- 允许头漏加 Authorization:带令牌跨域请求被预检拦截。
- 来源规则过宽:非信任站点可跨域读取。
追问
- 待确认:来源匹配正则/前缀配置方式,以插件文档核对。
- 开发环境能放开来源吗?答:可仅在开发环境放宽,生产必须精确配置。
06.8.1.2-073 预检 OPTIONS 请求如何处理?
一句话结论
CORS 插件自动响应预检 OPTIONS:根据请求头与方法返回允许信息并短路;业务 Handler 不应自行处理预检;预检通过后浏览器才发送实际请求。
概念解释
预检发生在实际请求前,浏览器询问服务端是否允许该来源、方法、自定义头。插件生成 OPTIONS 响应,不进入业务逻辑。预检缓存可减少重复询问,缓存时间按插件配置。
原理流程
- 浏览器发送 OPTIONS 预检,带来源、方法、头。
- 插件匹配配置并返回 CORS 头。
- 预检通过,发送实际请求。
- 预检失败,浏览器阻止实际请求发出。
代码或图示
OPTIONS /api/... -> CORS 插件响应(预检)
GET/POST /api/... -> 业务 Handler
常见误区
- 业务路由手写 OPTIONS 处理器:与插件响应重复或冲突。
- 预检未放行自定义头:实际请求不发出,排查时只看到预检失败。
追问
- 待确认:Ktor CORS 插件预检响应与缓存头配置,以文档核对。
- 预检失败看什么日志?答:CORS 响应头与浏览器控制台,业务日志通常无记录。
06.8.1.2-074 凭据型 CORS 配置有哪些注意点?
一句话结论
允许携带 Cookie/凭据时,来源不能用通配符,必须精确匹配;同时开启凭据标志;Cookie 的 SameSite、Secure 等属性配套配置;跨域凭据方案仍需 CSRF 防护。
概念解释
凭据模式下浏览器对来源校验更严格:通配来源与凭据不能共存。配置允许凭据后,任何被允许的来源都能携带站点 Cookie 调用,来源清单必须严格信任。自定义头令牌方式与 Cookie 凭据方式的 CORS 要求不同。
原理流程
- 配置精确允许来源。
- 开启凭据允许标志。
- 配套 Cookie 安全属性。
- 按 CSRF 防护方案校验跨站请求。
代码或图示
凭据模式:Allow-Origin 精确 + Allow-Credentials: true
禁止:Origin: * 与凭据同时使用
常见误区
- 图省事来源设通配:浏览器拒绝携带凭据。
- 开了凭据却不做 CSRF 防护:跨站请求可被利用。
追问
- 待确认:Ktor CORS 凭据配置属性名,以官方文档核对。
- Bearer 令牌跨域需要凭据标志吗?答:头携带方式不同,凭据标志针对 Cookie 自动携带场景。
06.8.1.2-075 Compression 插件如何选择编码器?
一句话结论
压缩插件按请求 Accept-Encoding 与响应内容选择编码器(gzip/deflate 等,具体支持列表以版本为准);可配置编码优先级与排除条件;对已压缩内容(图片、视频、压缩包)不再二次压缩。
概念解释
压缩在响应写出阶段包裹:根据客户端支持的编码与响应类型挑选编码器。编码器选择受内容大小、类型与配置影响;压缩占用 CPU,解压在客户端,需权衡延迟与带宽。
原理流程
- 请求携带 Accept-Encoding。
- 插件匹配可用编码器。
- 响应内容满足压缩条件则编码并设 Content-Encoding。
- 不满足条件按原内容写出。
代码或图示
install(Compression) {
gzip { /* 最小大小等配置 */ }
}
常见误区
- 对已是压缩格式的文件再压缩:CPU 浪费且收益很小。
- 不核对支持的编码器列表:按记忆写可能不被支持。
追问
- 待确认:Ktor 3 Compression 支持的编码器与配置 DSL,以官方文档核对。
- 压缩阈值怎么定?答:小文本不压缩,按内容类型与大小配置最小阈值。
06.8.1.2-076 压缩对哪些响应生效,如何排除?
一句话结论
可按内容类型、大小与响应条件排除:静态压缩资源、流式下载、实时日志等场景可不压缩;排除规则在插件配置中声明,避免对不该压缩的内容强行编码。
概念解释
排除维度:媒体类型、报文大小、响应形态。动态 JSON/文本通常收益明显;已压缩二进制与大文件传输不适合 CPU 压缩。压缩插件与缓存插件配合时注意缓存键是否含编码信息。
原理流程
- 列出响应类型与大小分布。
- 配置可压缩类型与最小阈值。
- 排除二进制与流式场景。
- 压测观察 CPU 与带宽收益。
代码或图示
压缩:JSON、文本、HTML
排除:图片、视频、压缩包、部分流式响应
常见误区
- 全量压缩不设阈值:小报文压缩反而增大体积。
- 代理缓存未区分编码:解压版本被错误缓存。
追问
- 待确认:排除条件配置方式(类型/大小),以插件文档核对。
- 压缩与响应包装插件顺序?答:先包装生成内容,再压缩写出,顺序按管道阶段确认。
06.8.1.2-077 ConditionalHeaders 协商缓存如何工作?
一句话结论
ConditionalHeaders 根据响应资源生成 Last-Modified/ETag 校验头,客户端带 If-Modified-Since/If-None-Match 请求时未变化返回 304,避免重复传输 body。
概念解释
协商缓存让客户端在资源未变时只收状态码。ETag 是资源版本标识,Last-Modified 是时间戳。校验依赖可稳定计算资源版本;动态易变内容不适合强协商缓存。
原理流程
- 首次响应携带 ETag/Last-Modified。
- 后续请求带校验头。
- 插件/处理器比对资源版本。
- 未变化返回 304,变化返回完整响应。
代码或图示
首次:ETag: "v1"
后续:If-None-Match: "v1" -> 304 Not Modified
常见误区
- 动态内容也算 ETag:版本频繁变化,协商收益低。
- ETag 生成不稳定:同一资源每次标识不同,缓存失效。
追问
- 待确认:Ktor 3 ConditionalHeaders 配置与自动校验行为,以官方文档核对。
- 304 响应要带 body 吗?答:不带 body,只带缓存相关头。
06.8.1.2-078 CachingHeaders 与 Cache-Control 如何设置?
一句话结论
CachingHeaders 插件按响应类型配置 Cache-Control 指令(max-age、私有/公开、不可变、no-cache 等);版本化静态资源长缓存,动态与敏感响应禁止缓存或私有短缓存。
概念解释
Cache-Control 控制浏览器与共享代理缓存行为。指令选择看资源可公开性与版本化程度:带内容哈希的资源可长缓存,接口响应默认不缓存,用户相关响应必须私有。
原理流程
- 区分资源类型与敏感性。
- 按类型配置缓存指令与时长。
- 响应写出头。
- 客户端/代理按指令缓存。
代码或图示
install(CachingHeaders) {
// 按响应类型配置 Cache-Control;具体 DSL 以文档为准
}
常见误区
- 接口响应被共享缓存:其他用户拿到缓存数据。
- 未版本化资源长缓存:发版后客户端拿旧文件。
追问
- 待确认:CachingHeaders 插件配置方式与可用指令,以官方文档核对。
- 敏感响应加什么指令?答:private + no-cache 或短 max-age,按安全基线。
06.8.1.2-079 静态与动态响应的缓存策略有何差异?
一句话结论
静态资源可版本化后长缓存并配合协商缓存;动态接口响应按用户私有或不缓存,缓存键包含主体与必要维度;缓存策略在网关、服务端与客户端三层保持一致。
概念解释
静态资源内容固定、可按文件名版本化;动态响应随主体、时间、权限变化。错误响应与鉴权响应不应被共享缓存。缓存分层:浏览器、代理 CDN、服务端缓存各自策略明确。
原理流程
- 静态资源:文件名带哈希,长 max-age + 不可变。
- 动态响应:私有或 no-cache。
- 共享缓存场景按主体与参数构造键。
- 失效与发布策略配套。
代码或图示
静态:/assets/app.<hash>.js -> 长缓存
动态:/api/me -> 私有 / 不缓存
常见误区
- 动态列表接口被 CDN 共享缓存:串用户数据。
- 静态资源不版本化:长缓存导致陈旧。
追问
- 待确认:服务端缓存头与代理缓存的配合规则,按部署架构核对。
- 缓存失效怎么做?答:版本化文件名或主动失效,按发布流程。
06.8.1.2-080 响应头插件之间的顺序有什么影响?
一句话结论
压缩、缓存、CORS、自定义头插件按管道层次包裹:内容生成在前,压缩与头补充在后;顺序错误可能导致头被覆盖、压缩作用于错误内容;调整后用实际响应报文核对头集合。
概念解释
各插件写入不同响应头,但包裹层次决定谁先谁后。CORS 头需对预检与实际响应都生效;缓存头与压缩编码应共存不冲突。装配顺序按「生成内容 -> 协商/缓存 -> 压缩 -> 补充安全头」梳理。
原理流程
- 梳理各插件写入的头与处理阶段。
- 按内容生成到写出的顺序安装。
- 用样例请求观察最终响应头。
- 冲突时明确各插件职责边界。
代码或图示
内容序列化 -> 缓存/协商头 -> 压缩编码 -> CORS/安全头
常见误区
- 多个插件重复写同一头:后写覆盖先写。
- 压缩在缓存头之前处理:缓存键未考虑编码。
追问
- 待确认:各响应插件在 Ktor 3 中的默认阶段,以官方文档核对。
- 头冲突如何排查?答:抓实际响应报文,按插件日志定位写入来源。
06.8.1.2-081 请求参数校验在哪一层做?
一句话结论
路径/查询/表单参数在进入业务服务前由路由层或公共校验器完成类型、格式、范围与必填校验;校验失败短路 400,业务服务只接收已校验类型化值;复杂业务规则在服务层判定。
概念解释
分层校验:输入格式与合法性在入口层,业务一致性与权限规则在服务层。入口校验避免脏数据进入业务逻辑;公共解析器复用规则,减少 Handler 内重复代码。
原理流程
- Handler/拦截器读取原始参数。
- 公共校验器做类型、格式、范围校验。
- 失败返回 400 错误结构。
- 合法值传入服务层。
代码或图示
val page = call.parameters["page"]?.toIntOrNull()?.takeIf { it > 0 }
?: return@get call.respond(HttpStatusCode.BadRequest)
常见误区
- 校验散落到业务服务:入口已放过非法参数。
- 只做类型转换不做范围校验:分页大小无限放大。
追问
- 待确认:是否有参数校验插件/扩展可复用,以生态文档核对;否则公共扩展函数实现。
- 嵌套 body 校验在哪做?答:反序列化后按 DTO 规则校验,字段级错误归一返回。
06.8.1.2-082 校验错误响应如何统一?
一句话结论
校验失败返回 400 与统一错误结构:错误码、字段、可读原因;多条字段错误列表返回;消息中性不暴露内部规则;日志记录原始输入特征与 trace 标识。
概念解释
统一错误结构让客户端能批量展示字段错误。区分语法错误(反序列化失败)与语义校验错误(范围、格式),两类都归 400 但错误码可细分。校验规则集中在公共校验器,保证响应格式一致。
原理流程
- 校验器收集字段错误。
- 无错误放行;有错误构造错误响应。
- 状态码 400,body 带字段错误列表。
- 日志记录不包含敏感明文。
代码或图示
data class FieldError(val field: String, val message: String)
data class ValidationError(val code: String, val errors: List<FieldError>)
常见误区
- 不同 Handler 返回不同错误格式:客户端分支混乱。
- 校验异常堆栈回显给前端:泄露内部实现。
追问
- 待确认:校验异常到状态码的映射位置,与 StatusPages 配合核对。
- 密码等敏感字段错误怎么提示?答:不回显原值,只给字段级中性提示。
06.8.1.2-083 限流维度与存储如何选型?
一句话结论
限流主体按场景选 IP、用户、租户或接口;单机用内存计数,分布式用共享存储(Redis 等);算法选固定窗口、滑动窗口或令牌桶,按接口突发特征选择;计数存储要考虑时钟一致与失效。
概念解释
限流保护后端不被突发打垮。维度决定公平性与绕过难度:匿名按 IP,登录后按用户,内部按租户。存储选择取决于实例数与配额一致性要求;内存快但多实例不准,共享存储一致但有网络开销。
原理流程
- 确定限流主体与配额。
- 单机或分布式存储选型。
- 选择计数算法与窗口。
- 超限返回 429 与重试提示。
代码或图示
维度:IP / 用户 / 租户 / 接口
存储:单机内存 / 分布式缓存
算法:固定窗口 / 滑动窗口 / 令牌桶
常见误区
- 多实例用本地计数:总配额成倍放大。
- 窗口边界突发未考虑:固定窗口临界流量翻倍。
追问
- 待确认:Ktor 3 是否有官方/成熟限流插件,以生态文档核对;多数场景需自实现拦截器。
- 超限响应带什么头?答:Retry-After 或配额剩余信息,按 API 约定。
06.8.1.2-084 CSRF 防护在服务端如何落地?
一句话结论
浏览器会话场景用 SameSite Cookie、CSRF Token 或双重提交 Cookie 方案;关键写操作校验请求来源/令牌;服务端不能只靠前端隐藏字段;Bearer 令牌 API 不存在传统 CSRF 问题,但仍需其他防护。
概念解释
CSRF 利用浏览器自动携带会话 Cookie 的特性伪造跨站请求。防御:Cookie SameSite 属性、服务端校验 CSRF Token、校验自定义头或来源。无 Cookie 的 Bearer 方案不自动携带凭据,攻击面不同。
原理流程
- 会话 Cookie 设置 SameSite 与安全属性。
- 表单/页面下发 CSRF Token。
- 写操作请求携带并校验 Token。
- 校验失败拒绝请求。
代码或图示
防护组合:SameSite Cookie + CSRF Token 校验 + 关键操作来源校验
常见误区
- 只依赖前端隐藏 Token 不在服务端校验:形同虚设。
- 用 Bearer 令牌却照搬 CSRF 流程:方案不匹配。
追问
- 待确认:Ktor 生态是否提供 CSRF 插件,以官方/第三方文档核对。
- 跨站读取风险由什么防?答:CORS 来源限制与认证授权配合。
06.8.1.2-085 XSS 防护的服务端边界是什么?
一句话结论
服务端负责输出编码/转义、设置 Content-Type 与相关安全头、校验输入;最终脚本执行发生在浏览器,前端模板与渲染同样需要转义;服务端不能替代前端渲染层防护。
概念解释
XSS 分存储型、反射型与 DOM 型。服务端可做:响应正确媒体类型、内容安全策略头、入库与输出编码、富文本白名单过滤。DOM 型 XSS 主要在前端渲染链路,服务端输入过滤无法完全覆盖。
原理流程
- 输入进入时做格式约束。
- 输出按目标上下文(HTML/属性/JS)编码。
- 设置 CSP、X-Content-Type-Options 等头。
- 富文本走白名单过滤。
代码或图示
服务端:输出编码 / 安全头 / 富文本白名单
前端:模板转义 / 安全 DOM 渲染
常见误区
- 只在入库时过滤:输出到不同上下文仍需编码。
- 把用户内容当 HTML 直接拼响应:脚本注入。
追问
- 待确认:Ktor 是否内置安全头插件,以官方文档核对;其余头可在拦截器统一添加。
- 富文本怎么保留安全标签?答:白名单标签与属性过滤,禁止脚本事件属性。
06.8.1.2-086 安全响应头如何统一添加?
一句话结论
在全局拦截器或安全头插件统一补充:CSP、X-Content-Type-Options、X-Frame-Options、Referrer-Policy、HSTS(HTTPS 场景);按响应类型区分策略,测试验证头集合与预检行为。
概念解释
安全头由服务端声明浏览器行为:禁止 MIME 嗅探、限制嵌入框架、内容来源策略、引用信息限制、强制 HTTPS。头策略与页面形态相关:纯 API 与 HTML 站点配置不同,避免 CSP 误拦业务资源。
原理流程
- 梳理站点/接口形态所需头。
- 全局拦截器或插件追加响应头。
- HTTPS 环境启用 HSTS。
- 浏览器与代理行为按头验证。
代码或图示
常用头:
X-Content-Type-Options: nosniff
X-Frame-Options: DENY/SAMEORIGIN
Referrer-Policy: ...
Content-Security-Policy: ...
常见误区
- HSTS 在 HTTP 环境提前启用:客户端被强制升级后无法回退。
- CSP 规则过严误拦静态资源:需要逐级放行验证。
追问
- 待确认:Ktor 3 安全头相关插件与配置,以官方文档核对。
- 头在哪个阶段加合适?答:响应提交前的全局拦截,确保所有响应覆盖。
06.8.1.2-087 输入清洗与输出编码有什么区别?
一句话结论
输入清洗改变或约束入库数据,输出编码按输出上下文转义展示;两者目的不同,不能互相替代;存储型 XSS 最终靠输出上下文编码防御,输入过滤只做辅助约束。
概念解释
输入清洗处理恶意与非法格式,但无法预知所有输出上下文;输出编码把特殊字符转成安全展示形式。同一数据输出到 HTML、属性、JS、URL 需要不同编码。清洗规则过严会破坏正常内容(如富文本)。
原理流程
- 输入层:格式校验、非法字符约束、富文本白名单。
- 存储:保留原始但受控的数据。
- 输出层:按目标上下文编码。
- 前端渲染继续转义。
代码或图示
输入:约束与过滤(不替代编码)
输出:HTML / 属性 / JS / URL 各自编码
常见误区
- 以为入库过滤一次就安全:输出到新上下文仍可能注入。
- 输出统一当纯文本编码:破坏富文本展示。
追问
- 特殊字符存不存原始值?答:按业务需要存储,输出时编码,避免不可逆清洗破坏数据。
- 富文本白名单在哪做?答:服务端过滤标签与事件属性,前端不再执行未过滤 HTML。
06.8.1.2-088 上传与入参大小、类型如何限制?
一句话结论
限制请求体与各部件大小、文件类型与扩展名、字段长度;超限拒绝并释放流;上传目录独立且路径防穿越;大小限制在读取层尽早生效,不在全量入内存后判断。
概念解释
入参限制包括 body 总量、字符串长度、数组/集合上限、上传部件数量与大小。类型校验看内容头与文件头,不仅看扩展名。限制策略防大报文打爆内存、防恶意文件落盘。
原理流程
- 声明 body 与部件上限。
- 接收过程累计大小,超限中断。
- 校验类型、扩展名与内容特征。
- 受控落盘或拒绝。
代码或图示
限制项:body 总量 / 字段长度 / 集合大小 / 部件数量 / 文件类型
常见误区
- 全量读完再判大小:大报文已进内存。
- 只校验扩展名:伪装类型文件可绕过。
追问
- 待确认:Ktor 3 请求体大小限制配置入口,以引擎/插件文档核对。
- 临时文件放哪里?答:独立临时目录,请求结束清理,禁止拼用户输入路径。
06.8.1.2-089 同一子树如何同时支持 JWT 与 Basic?
一句话结论
注册两个命名 provider,认证块同时引用;任一有效凭据即通过,产出统一 principal 类型;下游不区分来源做授权,需要时主体内记录凭据类型;组合策略与挑战行为按版本 API 核对。
概念解释
多方案共存用于同时面向人类后台与机器调用。统一主体模型让授权层一致;不同方案的安全策略(传输、哈希、过期)各自独立。provider 顺序影响挑战响应,不影响通过后的主体结构。
原理流程
- 定义 JWT 与 Basic provider。
- 认证块引用两个名称。
- 请求携带任一有效凭据通过。
- 映射为统一 principal 进入业务。
代码或图示
authenticate("jwt-auth", "basic-auth") {
get("/service") { /* 统一主体 */ }
}
常见误区
- 两套方案产出不同主体类型:下游取值分支混乱。
- Basic 走明文 HTTP:与 JWT 混用降低整体安全。
追问
- 待确认:Ktor 3 多 provider 任一通过/全部通过的策略配置,以官方文档核对。
- 如何区分调用来源?答:principal 中记录方案标识,审计按来源统计。
06.8.1.2-090 角色与权限校验放在哪一层?
一句话结论
粗粒度角色在授权拦截层按子树统一校验;细粒度数据权限在 Handler/服务层按主体与资源归属判定;认证只产出主体,授权不混入 provider 校验逻辑。
概念解释
角色是主体属性,权限是主体对资源的操作许可。角色校验可前置到路由子树,资源归属(本人订单、本租户数据)必须在访问具体资源时判定。两层都要可测试、可枚举回归。
原理流程
- 认证产出 principal 含角色。
- 拦截层按子树要求校验角色。
- Handler/服务层校验资源归属。
- 不通过返回 403。
代码或图示
if (principal.roles.contains("ADMIN")) {
// 放行
} else {
call.respond(HttpStatusCode.Forbidden)
}
常见误区
- 角色判断散落在 Handler 各处:遗漏接口形成越权。
- 只校验角色不校验数据归属:横向越权。
追问
- 权限清单放哪里?答:主体携带或服务层查询,按权限模型设计;不要在代码里硬编码散点判断。
- 待确认:Ktor 生态是否有授权注解/拦截扩展,以文档核对。
06.8.1.2-091 水平越权如何在 Handler 层防护?
一句话结论
访问资源时用主体标识与资源归属比对:只能访问本人/本租户数据;路径参数中的资源 id 不能直接信任,必须查出归属再判定;缺失归属记录按 404 或 403 统一处理。
概念解释
水平越权指同权限级别的用户互访数据。防御点在数据查询层:查询条件带主体/租户约束,而不是先取资源再判断。响应不区分「不存在」与「无权访问」时避免枚举,按安全约定选择状态码。
原理流程
- 从主体取当前用户/租户标识。
- 查询资源时带归属条件。
- 未查到按统一拒绝处理。
- 操作类接口同样校验归属后再执行。
代码或图示
val order = ordersRepository.findForUser(orderId, principal.userId)
?: return@get call.respond(HttpStatusCode.NotFound)
常见误区
- 按 id 查出资源再判断归属:归属条件未进查询,竞态与遗漏风险。
- 不同归属返回不同提示:辅助枚举资源存在性。
追问
- 待确认:项目数据权限约定以 06.1/06.11 通用安全题为准,本节只落地 Ktor 位置。
- 批量接口怎么防?答:列表查询强制带主体条件,禁止跨主体批量取数。
06.8.1.2-092 多端调用方(Web、开放 API、内部服务)认证如何划分?
一句话结论
按调用方类型划分 provider 与路由域:浏览器站点用会话 Cookie,开放 API 用令牌或签名,内部服务用服务凭据/双向认证;各域独立校验策略、权限范围与审计规则,凭据互不通用。
概念解释
不同调用方的威胁模型不同:浏览器防 XSS/CSRF,开放 API 防重放与泄露,内部服务防网络越权。按路由域隔离认证配置,主体类型区分调用方,日志与限流按域统计。
原理流程
- 定义调用方类别与信任边界。
- 各域装配对应 provider。
- 路由域引用各自认证策略。
- 授权与审计按调用方类型细分。
代码或图示
/web -> 会话 Cookie
/openapi -> Bearer 令牌 / 签名
/internal -> 服务凭据 / mTLS
常见误区
- 一套令牌通吃所有调用方:权限与撤销粒度粗放。
- 内部服务走公网开放接口:缺少网络层隔离。
追问
- 待确认:内部服务 mTLS 在引擎/网关层的配置位置,按部署架构核对。
- 调用方标识放哪里?答:principal 中记录类型与标识,审计按维度拆分。
06.8.1.2-093 匿名与已认证混合接口如何设计?
一句话结论
需要个性化时用可选认证:主体存在走登录逻辑,缺失走匿名逻辑;响应按主体区分缓存;强制公开内容不依赖主体;混合接口的错误处理对匿名与登录态分别明确。
概念解释
混合接口提升体验但增加分支:响应内容、缓存键、限流维度都要区分匿名与登录态。可选认证不能把非法令牌当匿名放行;前端按响应标识判断是否需要登录。
原理流程
- 接口声明可选认证。
- 读取可空主体。
- 分支生成对应响应。
- 缓存与限流按主体维度处理。
代码或图示
val principal = call.principal<UserPrincipal>()
val view = if (principal != null) personalized(principal) else anonymousView()
常见误区
- 匿名分支也访问登录态数据:越权泄露。
- 响应缓存不区分主体:登录内容被匿名命中。
追问
- 待确认:可选认证 provider 配置方式,以官方文档核对。
- 非法令牌在可选模式怎么处理?答:按策略拒绝或忽略,不能静默变匿名,安全上需明确约定。
06.8.1.2-094 主体过期如何实现无感刷新?
一句话结论
访问令牌短时效,前端 401 时用刷新令牌换新访问令牌;刷新接口独立认证,失败再引导登录;服务端不保存访问令牌状态,刷新令牌可吊销;多端刷新令牌分别管理。
概念解释
无感刷新发生在客户端请求链路:拦截 401 -> 调刷新 -> 重试原请求;刷新并发去重避免同时多次刷新。服务端关注刷新令牌校验、轮换与吊销,不感知前端重试细节。
原理流程
- 访问令牌过期,请求返回 401。
- 客户端携带刷新令牌换取新访问令牌。
- 刷新成功重试原请求;失败清除登录态。
- 刷新令牌轮换或失效后重新登录。
代码或图示
请求 401 -> 刷新令牌换发 -> 重试原请求
刷新失败 -> 清除会话 -> 重新登录
常见误区
- 多个请求同时过期并发刷新:刷新令牌被多次轮换失效。
- 刷新令牌长期有效不可吊销:泄露后无法收回。
追问
- 待确认:项目前端刷新流程不在本节展开,服务端只提供签发与校验接口。
- 刷新接口限流吗?答:按主体/设备维度限流,防刷新令牌爆破。
06.8.1.2-095 场景:开放 API 密钥签名认证如何接入?
一句话结论
为开放调用方分配 AccessKey 与 SecretKey,请求带标识与签名(方法、路径、参数、时间戳、随机串),服务端按相同规则重算签名比对;校验时间戳防重放,密钥可轮换与吊销。
概念解释
签名认证适合服务间开放 API:不传共享密钥,传签名摘要。服务端按 AccessKey 查密钥,拼接规范串用约定算法计算摘要,恒定时间比对。时间戳与 nonce 防重放,密钥按调用方隔离存放。
原理流程
- 调用方用 SecretKey 对规范请求串签名。
- 请求带 AccessKey、时间戳、nonce、签名。
- 服务端查密钥,重算签名并比对。
- 校验时间窗口与 nonce 后放行。
代码或图示
签名串:method + path + sortedParams + timestamp + nonce
服务端:同规则重算 -> 恒定时间比对 -> 时间戳/nonce 校验
常见误区
- 密钥在日志或报文里出现:泄露即可伪造签名。
- 不校验时间戳与 nonce:截获请求可重放。
追问
- 待确认:签名算法与 nonce 存储方案按项目规范;Ktor 侧在前置拦截器实现校验。
- 密钥轮换怎么做?答:双密钥过渡期,新签名用新密钥,旧密钥到期下线。
06.8.1.2-096 场景:管理后台 Session 与前端 Token 双模式如何共存?
一句话结论
管理后台浏览器走会话 Cookie,独立前端/移动 API 走令牌;两套认证 provider 分别挂在不同路由域,主体模型可统一;会话与令牌的过期、吊销、审计策略分别配置,凭据不跨模式复用。
概念解释
双模式常见于既有后台与新端侧接口并存。路由域隔离避免 Cookie 与令牌互相干扰;统一主体与权限模型让授权层一致。网络层与网关按域选择认证要求,避免公网暴露后台会话接口。
原理流程
- 划分后台路由与 API 路由。
- 分别装配 Session 与 Token provider。
- 统一 principal 结构与授权规则。
- 过期、吊销、审计按模式分别实现。
代码或图示
/admin/* -> Session Cookie(含 CSRF 防护)
/api/* -> Bearer 令牌
常见误区
- 两套模式挂在同一组路由:凭据处理逻辑混杂。
- 后台会话接口暴露到开放网关:缺少网络隔离。
追问
- 待确认:Session 插件与 JWT provider 共存的装配顺序,以官方文档核对。
- 统一主体字段怎么设计?答:公共标识 + 模式/来源标识,权限字段一致。
06.8.1.2-097 插件装配顺序的安全检查清单有哪些?
一句话结论
上线前核对:认证在业务 Handler 之前、CORS 不放开凭据通配来源、安全头全局覆盖、序列化在响应包装之后、限流在认证前后按维度生效;用匿名与跨域用例回归全部受保护路径。
概念解释
顺序类问题多在测试环境难发现,靠清单化核对。安全相关插件层次:前置拦截(限流、来源、认证)-> 业务 -> 响应处理(包装、序列化、压缩、头)。每个插件的阶段与包裹对象在评审时明确。
原理流程
- 画出插件包裹层次图。
- 核对安全插件位于 Handler 前。
- 核对响应插件顺序不冲突。
- 跑匿名、跨域、超限、非法报文回归。
代码或图示
检查项:认证位置 / CORS 来源 / 安全头覆盖 / 限流维度 / 序列化顺序
常见误区
- 只测正常登录路径:匿名与跨域未回归。
- 新增接口忘记挂认证:路由块位置审查遗漏。
追问
- 待确认:各插件默认阶段,以官方 pipeline 文档核对后画层次图。
- 评审记录什么?答:插件顺序、职责边界、未覆盖的异常路径。
06.8.1.2-098 序列化有哪些安全注意点?
一句话结论
限制反序列化类型与深度,避免反序列化不可信多态类型;校验输入字段与大小;服务端 DTO 与领域实体分离;依赖序列化库打补丁,不解析未知危险格式;错误响应不泄露内部类型信息。
概念解释
反序列化漏洞来自构造恶意报文触发危险类型实例化或资源耗尽。kotlinx/Jackson 配置应关闭危险多态默认行为,限制嵌套深度与集合大小。输入只映射到白名单 DTO,不直接反序列化业务实体图。
原理流程
- DTO 字段白名单映射。
- 限制深度、集合与字符串大小。
- 关闭不安全多态/默认类型处理。
- 异常兜底为中性错误响应。
代码或图示
安全项:白名单 DTO / 深度限制 / 集合上限 / 关闭危险多态 / 库版本维护
常见误区
- 直接把请求反序列化成领域实体:暴露内部结构与关联。
- 不限制嵌套深度:恶意深嵌套打爆 CPU/内存。
追问
- 待确认:所用序列化库的深度/大小限制配置项,以库安全文档核对。
- 依赖漏洞怎么跟踪?答:定期扫描序列化库版本,按补丁升级。
06.8.1.2-099 生产认证配置常见漏配有哪些?
一句话结论
常见漏配:令牌不校验 issuer/audience、算法未固定、密钥进仓库、Cookie 缺安全属性、错误 401/403 混用、黑名单缺失、日志记录凭据、公开接口误挂或漏挂认证;上线前逐项清单核对。
概念解释
漏配多为默认配置未按生产基线收紧。核对维度:验签要素、密钥管理、Cookie 属性、状态码语义、撤销机制、日志脱敏、路由保护面。清单化在部署前检查,避免依赖代码评审记忆。
原理流程
- 按清单核对验签与密钥配置。
- 核对 Cookie 与响应头属性。
- 枚举路由确认认证挂载。
- 检查日志不含凭据明文。
代码或图示
漏配清单:声明校验 / 算法固定 / 密钥管理 / Cookie 属性 / 状态码 / 撤销 / 日志脱敏 / 路由覆盖
常见误区
- 开发配置复制到生产:放宽项未收回。
- 日志打印 Authorization 头:凭据随日志泄露。
追问
- 待确认:各 provider 默认安全配置是否够生产基线,以官方安全文档核对。
- 漏配怎么回归?答:匿名、过期、伪造、跨域用例枚举全部接口。
06.8.1.2-100 Ktor 认证与序列化生态相对传统框架能力如何对比?
一句话结论
Ktor 以插件 DSL 与协程管道组织认证/序列化,装配显式、轻量;传统框架依赖容器注解与自动装配,生态资料与企业集成更成熟;能力覆盖上两者都能完成常见认证与 JSON 场景,选型看团队与既有生态,本节不展开传统框架细节。
概念解释
对比维度:装配方式、插件成熟度、文档与招聘、与既有体系集成。Ktor 自定义管道灵活,但某些企业级认证组件生态不如传统框架丰富;落地前验证所需方案(JWT、Session、OAuth 等)在生态中的成熟度。
原理流程
- 列出所需认证与序列化能力。
- 核对 Ktor 生态组件成熟度。
- 对比团队经验与集成成本。
- 概念验证覆盖关键安全路径。
代码或图示
Ktor:显式插件 DSL、协程管道、轻依赖
传统框架:容器装配、注解生态、企业集成成熟度
常见误区
- 假设 Ktor 生态与传统框架组件一一对应:小众方案可能需自研。
- 只看框架性能不看认证组件成熟度:安全落地成本被低估。
追问
- 待确认:Ktor 3 各认证/序列化组件当前维护状态,以官方与第三方仓库核对。
- 传统框架细节见 06.2 分册,本节不重复展开。
参考来源
- Ktor 认证文档:Authentication 插件、provider、principal 与 challenge 模型。
- Ktor 内容协商文档:ContentNegotiation 与序列化转换器配置。
- Ktor CORS 文档:跨域来源、方法、头与预检配置。
- Ktor 插件机制文档:自定义插件安装器、钩子与管道协作。
- kotlinx.serialization 文档:Kotlin 原生序列化配置与数据类标注。
待整理清单
- [ ] 核对 Ktor 3 Authentication provider DSL、principal 读取与 challenge 自定义入口
- [ ] 核对多 provider 组合策略(any/all)与可选认证配置方式
- [ ] 核对 JWT 插件坐标、验证器字段与异常类型(过期/伪造/算法不匹配)
- [ ] 核对 Session 插件存储、Cookie 属性与会话轮换 API
- [ ] 核对 ContentNegotiation 转换器注册签名与 kotlinx/Jackson 依赖坐标
- [ ] 核对 Compression、CachingHeaders、ConditionalHeaders、安全头插件的配置 DSL
- [ ] 梳理项目实际认证方案(JWT/Session/签名)与限流、CSRF、XSS 落地示例