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

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 协作。

原理流程

  1. 模块内 install(SomePlugin) { 配置 }。
  2. 安装器构造配置对象并注册拦截器到管道阶段。
  3. 请求进入阶段时执行插件前置/后置逻辑。
  4. 插件所需共享对象写入 Application 或 Call 属性。

代码或图示

install(ContentNegotiation) {
    json(Json { prettyPrint = true })
}

常见误区

  • 把插件当成独立服务启动:插件只是管道行为单元。
  • 在 Handler 内重复实现插件已覆盖的横切逻辑:分支遗漏。

追问

  • 插件配置在什么时机执行?答:装配期,详见本节后续题目。
  • 插件能改路由表吗?答:一般不能,路由表在装配阶段确定。

06.8.1.2-002 Plugin 与旧版 Feature 概念是什么关系?

一句话结论

现代 Ktor 以 Plugin 描述符与安装器为扩展单元;早期版本的 Feature 概念在演进中被插件机制替代,旧写法可能已弃用;具体改名与替代 API 以版本迁移文档为准,未核对前标「待确认」。

概念解释

面试只需说明扩展机制的演进脉络:从早期 Feature 装配器到当前插件描述符模型。不要凭记忆断言旧类名在 3.x 仍可用;代码迁移以编译告警和官方 changelog 为准。

原理流程

  1. 对照编译告警识别弃用的旧扩展写法。
  2. 查迁移指南找到对应插件安装入口。
  3. 替换为当前插件描述符 API。
  4. 回归验证拦截行为。

代码或图示

核对路径:编译告警 -> 官方迁移文档 -> 当前插件 install 写法

常见误区

  • 把旧 Feature 笔记当当前 API 答案:版本行为可能已变。
  • 只替换类名不核对拦截阶段:行为层次可能不同。

追问

  • 待确认:Ktor 3 中旧 Feature 相关 API 的废弃状态,以官方文档核对。
  • 自定义插件当前推荐入口是什么?答:createApplicationPlugin,签名见后续题目。

06.8.1.2-003 install 时插件配置闭包在什么时机执行?

一句话结论

配置闭包在装配期(引擎启动、Application 构建阶段)执行一次,此时没有任何请求;请求期逻辑必须由闭包注册的拦截器在 Call 上执行,不能在闭包里读取请求数据。

概念解释

装配期负责构造插件策略与默认值;请求期才接触 Call。混淆两个阶段会写出拿不到上下文的代码,或把请求级状态错误地固化进进程级配置。

原理流程

  1. 引擎加载模块,进入装配流程。
  2. install 调用配置闭包,读取环境配置。
  3. 注册请求期拦截器。
  4. 启动后请求到来,拦截器才访问 Call。

代码或图示

install(Authentication) {
    // 装配期:定义 provider 与策略
    jwt("jwt-auth") { /* ... */ }
}

常见误区

  • 闭包里取 call.parameters:装配期无 Call,编译或运行期报错。
  • 在闭包内缓存每请求值:进程级单例被请求污染。

追问

  • 配置需要按环境变化怎么办?答:装配期从 environment.config 读取,按环境给不同策略。
  • 插件能在装配期起后台协程吗?答:可以,但要绑定应用生命周期并在停机时取消。

06.8.1.2-004 插件描述符由哪些部分组成?

一句话结论

一个插件描述符包含名称、配置构造器、安装器逻辑;安装器内完成拦截注册、属性写入与生命周期订阅;现代 API 通过工厂函数生成描述符,业务方只通过 install 引用。

概念解释

名称用于识别与排障;配置类持有可选项;安装器是行为装配点。理解组成有助于读官方插件源码和写自定义插件,不需要背诵内部类名,不确定处以源码为准。

原理流程

  1. 定义插件配置类与默认值。
  2. 工厂函数生成带名称的描述符。
  3. 安装器内拦截管道、挂属性、订阅事件。
  4. install 时把配置闭包交给描述符。

代码或图示

PluginDescriptor:
- 名称(调试标识)
- 配置对象(策略参数)
- 安装器(拦截注册 / 属性 / 生命周期)

常见误区

  • 把配置对象当请求上下文用:生命周期不同。
  • 插件名称与其他插件重名:排障时难以定位。

追问

  • 待确认:Ktor 3 插件描述符接口与工厂函数签名,以官方插件文档核对。
  • 配置可不可变?答:建议装配后视为不可变,请求期不修改。

06.8.1.2-005 内置插件与自定义插件共用同一套机制吗?

一句话结论

共用同一套管道与安装机制:官方插件只是由框架维护的描述符,自定义插件遵循同样的 install 与拦截注册方式;区别在成熟度、默认配置与生态集成,不在运行时待遇。

概念解释

理解这一点后,读官方插件行为可以套用管道阶段模型;自定义插件能复用 Call、attributes、monitor 等基础能力。官方插件处理了边界与兼容,自研插件需自行覆盖异常与配置校验。

原理流程

  1. 识别要实现的横切能力属于哪个管道阶段。
  2. 按官方插件相同方式注册拦截。
  3. 自行补配置校验、异常兜底与测试。
  4. 复用框架提供的 Call 与属性 API。

代码或图示

// 自定义插件与官方插件都经 install 挂到同一 Application
install(MyPlugin) { setting = true }

常见误区

  • 认为自研插件能拿到特权内部接口:只能用公开扩展能力。
  • 忽略配置校验:自研插件非法输入可能启动期不失败、请求期才崩。

追问

  • 自研插件能依赖官方插件吗?答:可在同一管道协作,注意安装顺序与属性约定。
  • 插件发布复用形式?答:抽成公共模块函数或独立库,按项目依赖管理引入。

06.8.1.2-006 插件如何访问 Application 环境与配置?

一句话结论

安装器通过 application.environment.config 读取配置键,装配期解析为插件策略;请求期拦截器引用已解析的配置对象,不重复读配置源。

概念解释

环境配置包括应用配置、开发模式标识与日志。插件应提供默认值并在装配期校验必填项,缺失时启动快速失败;敏感配置从环境变量或密钥管理注入。

原理流程

  1. 安装器获取 Application 环境。
  2. 按 key 读取配置,合并默认值。
  3. 校验取值范围,构造不可变策略。
  4. 拦截器闭包引用策略对象。

代码或图示

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 会每次请求重建。

原理流程

  1. 判断对象生命周期:跨请求复用还是单次使用。
  2. 进程级对象装配时写入 application.attributes。
  3. 请求级值挂 call.attributes。
  4. 请求结束只清理 Call 属性。

代码或图示

val ClientKey = AttributeKey<MetricsClient>("MetricsClient")
application.attributes.put(ClientKey, MetricsClient(config))

常见误区

  • 在单例字段里缓存当前登录用户:并发串号。
  • 把连接池挂到 Call:请求结束被回收。

追问

  • 属性表键为什么用类型化 Key?答:避免字符串重名与弱类型强转。
  • 进程级状态如何释放?答:订阅停止事件关闭,见后续题目。

06.8.1.2-008 插件拦截器可以挂在哪些管道阶段?

一句话结论

插件按行为性质选择阶段:认证、CORS 等前置检查挂插件/调用前阶段,响应包装与压缩包裹 Handler,日志统计挂监控阶段;阶段选错会导致行为过早或过晚。

概念解释

阶段划分与框架管道一致:前置准备、插件装配、调用处理、结果监控。前置类必须在 Handler 之前拦截,观察类放在能拿到最终结果的位置。具体阶段常量名以版本为准。

原理流程

  1. 明确插件行为在请求链中的位置。
  2. 选取对应阶段注册拦截器。
  3. 前置逻辑在 proceed 前,收尾在 proceed 后。
  4. 监控类只读最终状态与异常。

代码或图示

intercept(ApplicationCallPipeline.Plugins) {
    // 前置:校验、补充请求信息
    proceed()
    // 后置:补充响应头
}

常见误区

  • 鉴权挂监控阶段:Handler 已执行,挡不住请求。
  • 日志挂前置阶段:拿不到最终状态码。

追问

  • 待确认:Ktor 3 可用阶段常量与顺序,以官方 pipeline 文档核对。
  • 一个插件能挂多个阶段吗?答:可以,按职责分别注册。

06.8.1.2-009 插件如何读取和修改响应?

一句话结论

拦截器在 proceed 后读取响应状态与头,可补充响应头;响应体由序列化插件或 Handler 生成,body 提交后不可回读重写,统一包装应在响应生成层处理。

概念解释

响应修改能力分层:状态码与头在提交前可改,body 内容在序列化/响应构造阶段介入。插件想统一包一层 envelope,应作用于响应对象序列化前,而不是写出后改写字节流。

原理流程

  1. Handler 产出响应对象。
  2. 序列化插件转为 body 并写头。
  3. 后置拦截补充或覆盖未提交的头。
  4. body 提交后进入网络写出。

代码或图示

intercept(ApplicationCallPipeline.Plugins) {
    proceed()
    call.response.headers.append("X-App-Version", version)
}

常见误区

  • body 写出后再读取重写:缓存行为不确定。
  • 多个插件各自包响应体:格式互相覆盖。

追问

  • 状态码能被后置拦截改吗?答:未提交前可以,已提交忽略。
  • 响应体包装在哪做合适?答:内容协商层或自定义响应包装插件。

06.8.1.2-010 插件依赖另一个插件时如何声明与协作?

一句话结论

跨插件协作通过管道顺序与 attributes 约定:被依赖插件先安装,把共享对象写入属性;依赖插件在之后阶段读取。依赖关系应在文档与装配顺序上明确,不依赖隐式偶然顺序。

概念解释

典型协作:认证插件写入 principal,后续授权或日志插件读取;序列化插件先于响应包装。安装顺序决定包裹层次,属性约定决定数据契约。隐式依赖在重构时容易断裂。

原理流程

  1. 明确数据生产方与消费方。
  2. 生产插件先安装并写属性 Key。
  3. 消费插件后安装,按 Key 读取并判空。
  4. 在模块装配中固化顺序。

代码或图示

认证插件(生产 principal) -> 授权/日志插件(消费 principal)

常见误区

  • 消费插件假设生产插件一定先装:顺序调换后取不到主体。
  • 属性 Key 命名不统一:跨插件取值失败。

追问

  • 待确认:Ktor 3 是否提供插件依赖声明 API,以官方文档核对。
  • 取不到依赖对象怎么办?答:装配期校验或请求期快速失败,不静默放行。

06.8.1.2-011 插件安装失败如何快速定位?

一句话结论

安装失败多为配置非法、缺失依赖或阶段冲突:先看装配期异常堆栈与插件名称,核对配置值与安装顺序,再用最小模块复现;请求期才暴露的问题多为阶段挂错或属性取不到。

概念解释

启动期失败:配置解析、必填项缺失、重复安装冲突。请求期失败:拦截阶段错误、上游插件未提供属性、响应被重复包装。两类问题定位路径不同,不要混在一起猜。

原理流程

  1. 区分失败时机:启动装配还是请求处理。
  2. 读异常堆栈定位插件与阶段。
  3. 核对配置项与依赖插件顺序。
  4. 最小模块复现后修复。

代码或图示

启动失败:配置 / 依赖缺失 / 重复安装
请求失败:阶段错误 / 属性缺失 / 响应冲突

常见误区

  • 启动失败就改业务代码:问题常在装配配置。
  • 忽略插件名称日志:多个同类插件时分不清。

追问

  • 如何输出插件装配清单?答:开发期日志或装配打印,具体能力以版本为准。
  • 配置非法应在哪层拦截?答:插件安装器校验,启动快速失败。

06.8.1.2-012 插件配置 DSL 如何定义?

一句话结论

为插件定义配置类(属性带默认值),安装工厂接收配置类构造器,install 闭包内修改属性;配置项按必填/可选区分,提供校验方法,保持装配后不可变。

概念解释

DSL 的价值是调用方可读、配置集中。配置类只放策略参数,不放请求上下文;复杂默认值在类初始化或安装器内解析。校验在安装器统一执行,避免每个请求重复检查。

原理流程

  1. 定义配置类与字段默认值。
  2. 工厂函数绑定配置类。
  3. install 闭包覆盖可选值。
  4. 安装器校验后冻结为策略对象。

代码或图示

class MyPluginConfig {
    var timeoutMs: Long = 1000
    var enabled: Boolean = true
}

常见误区

  • 配置类暴露可变集合被请求期修改:并发风险。
  • 配置项没有默认值与校验:调用方漏配时行为不确定。

追问

  • 嵌套配置怎么组织?答:配置类内部聚合成组,DSL 层级与之一致。
  • 待确认:工厂函数配置构造器参数签名,以官方 createApplicationPlugin 文档核对。

06.8.1.2-013 插件如何订阅应用生命周期事件?

一句话结论

通过 application.monitor.subscribe(事件) 订阅启动停止等生命周期节点,在停止事件中释放后台协程、客户端与连接池;订阅逻辑自行容错,避免一个清理失败阻断其余。

概念解释

生命周期订阅用于资源持有型插件:后台轮询、订阅消费者、共享客户端。事件触发时机在装配之后、停机流程之中;订阅回调不能再依赖已关闭的其他资源。

原理流程

  1. 插件安装时订阅启动/停止事件。
  2. 启动事件中初始化后台任务。
  3. 停止事件中取消 Job、关闭客户端。
  4. 清理异常记录日志但不中断其余释放。

代码或图示

application.monitor.subscribe(ApplicationStopping) {
    background.cancel()
    client.close()
}

常见误区

  • 不订阅停止事件:后台协程与连接随进程残留。
  • 清理流程抛异常未捕获:后续资源得不到释放。

追问

  • 待确认:Ktor 3 生命周期事件类型名称,以官方文档核对。
  • 启动事件适合做什么?答:预热缓存、建立连接,不要阻塞启动过久。

06.8.1.2-014 引入第三方插件要核对哪些点?

一句话结论

核对版本基线与兼容性、维护状态、配置边界、线程安全与异常处理、依赖体积与漏洞;在测试环境验证行为后再引入生产,不因为功能示例可用就直接上线。

概念解释

第三方插件可能绑定特定 Ktor 版本、自带传递依赖,或在请求期持有可变状态。评审重点:是否线程安全、异常是否吞掉、配置是否可观测、是否有安全相关默认值。

原理流程

  1. 核对插件版本与 Ktor/Kotlin 基线兼容。
  2. 审查源码或文档的线程模型与异常处理。
  3. 测试环境覆盖正常与失败路径。
  4. 评估依赖体积、漏洞维护与替代方案。

代码或图示

评审清单:版本兼容 / 维护活跃度 / 线程安全 / 异常兜底 / 依赖与漏洞

常见误区

  • 只看 README 示例:生产边界行为未验证。
  • 引入后不跟踪升级:已知漏洞长期暴露。

追问

  • 待确认:插件坐标与版本兼容矩阵,以官方仓库与发布说明核对。
  • 插件出问题如何回退?答:按模块隔离装配,可关闭插件或替换为自研实现。

06.8.1.2-015 如何用 createApplicationPlugin 写最小自定义插件?

一句话结论

用工厂函数创建插件描述符,安装器内注册一个管道拦截器;最小插件只做前置或后置动作,配置类可选;写完经 install 装配并在测试中验证拦截触发。

概念解释

最小示例帮助理解装配链路:描述符 -> 安装器 -> 拦截器 -> Call。先让插件能进入管道,再逐步加配置、属性与生命周期逻辑。API 签名以版本为准。

原理流程

  1. 调用插件工厂并命名。
  2. 安装器内 intercept 注册逻辑。
  3. 模块内 install 该插件。
  4. 测试发起请求观察拦截执行。

代码或图示

val LoggingPlugin = createApplicationPlugin("LoggingPlugin") {
    onCall { call ->
        application.log.info("${call.request.httpMethod} ${call.request.uri}")
    }
}

常见误区

  • 拦截器内直接读请求体:流可能已被消费。
  • 插件未 install:拦截器自然不触发。

追问

  • 待确认:onCall 对应的管道阶段与可用回调签名,以官方插件文档核对。
  • 最小插件需要配置类吗?答:无策略参数时可省略,需要可选项时再加。

06.8.1.2-016 自定义插件配置类如何组织?

一句话结论

配置类按策略分组,字段带默认值,提供校验方法;安装器把闭包修改后的配置转成不可变策略对象供拦截器使用,避免请求期直接触碰可变配置。

概念解释

配置组织原则:必填项显式声明,可选项给安全默认值;敏感配置不在配置类里硬编码。嵌套策略用内部类分组,DSL 调用方按组阅读。校验失败在装配期抛出。

原理流程

  1. 定义配置类与默认值。
  2. install 闭包覆盖配置。
  3. 安装器校验必填与取值范围。
  4. 生成不可变策略供拦截器引用。

代码或图示

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 顺序、前置后置包裹与短路。两者最终都注册到管道节点,行为层次需结合版本文档确认。

原理流程

  1. 场景只需要调用时观察:用 onCall 钩子。
  2. 需要前置校验、短路或包裹响应:用 intercept 选阶段。
  3. 钩子内部仍注册为管道拦截器。
  4. 复杂插件可组合多个钩子与拦截。

代码或图示

// 语义钩子:调用时动作
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 带类型,避免弱类型强转。

原理流程

  1. 定义共享 AttributeKey 与类型。
  2. 生产插件在拦截器写 call.attributes。
  3. 消费方按 Key 读取并判空。
  4. 请求结束属性随 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,避免重复响应;拒绝原因写日志,响应体中性。

原理流程

  1. 前置拦截读取请求所需信息。
  2. 校验失败:构造错误响应并 respond。
  3. 不 proceed,结束本次拦截。
  4. 通过则 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 场景。

原理流程

  1. 拦截器 proceed 拿到响应结果。
  2. 按状态与类型决定是否包装。
  3. 重写响应为包装结构。
  4. 序列化插件最终输出 body。

代码或图示

intercept(ApplicationCallPipeline.Call) {
    proceed()
    // 仅对 JSON 响应做包装;具体读取响应 API 以版本为准
}

常见误区

  • 对二进制/流式响应包文本外壳:破坏下载与分块。
  • 多个包装插件叠加:层级错乱。

追问

  • 待确认:拦截器中读取响应对象与重写响应的 API,以官方文档核对。
  • 错误响应在哪一层归一?答:异常处理插件或响应包装插件,二选一避免重复。

06.8.1.2-021 插件里启动后台协程要注意什么?

一句话结论

后台协程必须绑定应用 Job 生命周期,持有引用并在停止事件取消;不要挂请求作用域,不要用全局作用域放任泄漏;任务异常要有人消费并记录日志。

概念解释

插件常需要定时刷新缓存、推送订阅或批量同步。这类任务生命周期与应用一致,区别于请求协程。未取消的后台任务在停机后仍占用线程与连接,是常见泄漏源。

原理流程

  1. 装配期创建 SupervisorJob 作为根。
  2. 后台任务挂该 Job 启动。
  3. 订阅停止事件取消根 Job 并等待结束。
  4. 任务异常捕获记录,不静默崩溃。

代码或图示

val background = SupervisorJob()
application.monitor.subscribe(ApplicationStopping) { background.cancel() }

常见误区

  • 用 GlobalScope 起任务:停机取消不到。
  • 后台任务持有 Call 引用:请求结束后悬垂。

追问

  • 后台任务失败要重试吗?答:按任务性质配置有限重试与告警,避免无限循环。
  • 待确认:应用级 Job 可访问方式,以源码/文档核对。

06.8.1.2-022 插件如何订阅停机事件释放资源?

一句话结论

在安装期订阅停止事件,回调内按逆序取消后台任务、关闭客户端与池;每个释放动作容错并记录失败,设等待上限避免僵死资源拖住停机流程。

概念解释

资源释放顺序与创建相反:先停任务接收新工作,再关连接池。停止回调中不要再发起远程调用等待响应,否则停机延迟。释放失败应记录但继续清理其余资源。

原理流程

  1. 安装期注册停止回调。
  2. 停机触发:取消后台 Job。
  3. 关闭客户端、池与临时资源。
  4. 异常捕获记录,流程继续。

代码或图示

application.monitor.subscribe(ApplicationStopping) {
    runCatching { background.cancel() }
    runCatching { client.close() }
}

常见误区

  • 先关池再等任务结束:任务借已关闭池报错。
  • 一个资源释放异常中断后续清理:其余资源泄漏。

追问

  • 待确认:停止事件回调是否提供等待机制与超时参数,以官方文档核对。
  • 临时文件在哪删?答:任务结束或停机时清理,避免残留。

06.8.1.2-023 自定义插件如何写测试?

一句话结论

用测试应用装配插件,发起请求断言拦截行为:前置短路、属性写入、响应包装与日志;外部依赖替换为测试替身,覆盖正常、拒绝与异常路径。

概念解释

插件测试聚焦管道行为,不依赖真实端口。断言点:是否进入拦截、属性 Key 是否写入、短路响应状态码、包装结构是否正确。配置不同默认值各跑一遍用例。

原理流程

  1. 测试构造 Application 装配目标插件。
  2. 注入测试替身依赖。
  3. 发起各类请求。
  4. 断言响应、属性与调用交互。

代码或图示

testApplication {
    install(MyPlugin) { /* 测试配置 */ }
    val res = client.get("/")
    assertEquals(HttpStatusCode.Unauthorized, res.status)
}

常见误区

  • 只测放行路径:拒绝与异常分支未覆盖。
  • 断言日志文本:脆弱,应断言行为与状态。

追问

  • 待确认:测试启动器 API 在 Ktor 3 中的名称,以官方测试文档核对。
  • 插件单测能否脱离 Application?答:纯策略逻辑可单测,管道行为需测试应用。

06.8.1.2-024 自研插件常见坑点有哪些?

一句话结论

常见坑:阶段挂错导致鉴权失效、装配期读取请求上下文、请求值误存进程属性、重复安装行为叠加、资源未随停机释放、异常被吞掉无日志;逐一在评审与测试中核对。

概念解释

这些坑本质都是生命周期与阶段边界混淆。清单化排查:阶段是否正确、两个生命周期是否混用、安装是否幂等、资源是否释放、异常是否可见。自研插件上线前应过一遍该清单。

原理流程

  1. 评审插件阶段与短路逻辑。
  2. 核对属性生命周期归属。
  3. 检查重复安装与资源释放。
  4. 验证异常路径有日志与兜底响应。

代码或图示

坑点清单:阶段 / 上下文时机 / 属性归属 / 重复安装 / 资源释放 / 异常可见性

常见误区

  • 上线后才发现鉴权在 Handler 之后:测试未覆盖匿名请求。
  • 插件异常只记本地控制台:生产排障无记录。

追问

  • 插件如何避免重复安装?答:安装器做重复保护或在装配结构上保证单点安装。
  • 与官方插件冲突怎么办?答:核对阶段与包装层次,必要时二选一。

06.8.1.2-025 Authentication 插件的整体模型是什么?

一句话结论

Authentication 插件管理命名认证提供者,按引用把提供者挂到路由子树;请求经提供者校验后产出 principal,失败时触发 challenge 返回 401/403;授权(角色权限)在认证之后的 Handler 或拦截层完成。

概念解释

认证回答「你是谁」,授权回答「你能做什么」。插件内注册多个 provider(JWT、Basic、Session 等),路由块引用 provider 名称。校验通过把主体放入 Call,未通过由 challenge 生成响应。

原理流程

  1. install(Authentication) 内定义命名 provider。
  2. 路由块 authenticate("name") 引用 provider。
  3. 请求进入 provider 校验凭据,成功产出 principal。
  4. 失败触发 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)。

原理流程

  1. 认证 provider 校验凭据,构造 principal。
  2. 授权层读取 principal 与资源要求。
  3. 通过则进入 Handler,否则 403。
  4. 数据级权限在 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 为准,不凭记忆断言。

原理流程

  1. 安装 Authentication 时声明 provider 并命名。
  2. 配置校验逻辑、主体映射与挑战响应。
  3. 路由块按名称引用。
  4. 请求匹配到引用该 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 类型。

原理流程

  1. provider 校验通过,构造 principal 对象。
  2. 写入 Call 认证上下文。
  3. 下游按类型读取 principal。
  4. 读取失败按未认证处理。

代码或图示

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 层归一,避免每个受保护接口手写拒绝逻辑。

原理流程

  1. provider 校验未通过或未提供凭据。
  2. 调用 challenge 流程生成响应。
  3. 按方案设置状态码与协商头。
  4. 响应短路,不进入 Handler。

代码或图示

缺凭据 / 无效凭据 / 过期 -> challenge -> 401(或 403 场景)-> 响应短路

常见误区

  • Handler 内自行返回 401:绕过 challenge 统一规则。
  • 所有失败都返回同样消息:无法区分过期与无效,排障困难。

追问

  • 待确认:Ktor 3 challenge 自定义配置入口,以官方认证文档核对。
  • 403 由 challenge 产生吗?答:未认证归 401,已识别无权限归 403,后者多在授权层。

06.8.1.2-030 未认证与无权限响应有什么区别?

一句话结论

未认证(401)表示身份缺失或凭据无效,需重新登录/提供凭据;无权限(403)表示身份已识别但不具备该资源权限;两者状态码、响应头与客户端处理流程不同,不可混用。

概念解释

401 常携带认证协商头,403 不引导重新认证。响应体消息保持中性,不枚举用户是否存在。审计日志分别记录两类拒绝,便于发现爆破与越权尝试。

原理流程

  1. 认证阶段失败 -> 401 challenge。
  2. 认证通过、授权阶段失败 -> 403。
  3. 响应结构统一,消息中性。
  4. 拒绝事件记录主体标识(若有)与路径。

代码或图示

401:匿名 / 凭据无效 -> 引导重新认证
403:已登录但权限不足 -> 拒绝访问

常见误区

  • 登录用户访问越权资源返回 401:客户端误触发重新登录。
  • 403 响应提示「用户不存在」:辅助账号枚举。

追问

  • 待确认:认证插件默认状态码映射,以文档核对。
  • 接口同时可能 401/403 时怎么排?答:先确认主体是否取出,再看授权判定。

06.8.1.2-031 Basic 认证如何配置?

一句话结论

Basic provider 从 Authorization: Basic <base64> 解析用户名密码,调用校验函数比对凭据,成功产出 principal;配置 realm 标识;必须配合 HTTPS,否则凭据明文可被截获。

概念解释

Basic 是简单的传输编码而非加密:编码可被解码,安全性完全依赖传输加密。适合内部服务、调试或配合网关认证,不适合面向公网的浏览器会话。校验函数应使用安全的密码比对方式。

原理流程

  1. 安装 basic provider 并命名、设置 realm。
  2. 请求携带 Basic 头,provider 解码取出用户名密码。
  3. 校验函数核对凭据,成功构造 principal。
  4. 失败触发 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 当加密机制理解。

原理流程

  1. 确认全链路 HTTPS 终止位置与加密范围。
  2. 校验侧使用哈希与恒定时间比较。
  3. 日志输出剔除 Authorization 头。
  4. 网络层限制可访问来源。

代码或图示

安全清单:HTTPS / 密码哈希 / 日志脱敏 / 来源限制 / 方案适配场景

常见误区

  • 认为 Base64 是加密:可被任意解码。
  • 凭据出现在访问日志:泄露面扩大。

追问

  • 密码哈希算法怎么选?答:按项目安全基线选用慢哈希算法,具体参数按安全规范。
  • Basic 凭据能吊销吗?答:改密码或轮换密钥,没有独立会话状态可即时失效。

06.8.1.2-033 认证拦截如何挂到路由子树?

一句话结论

authenticate("provider-name") { ... } 块内注册的路由子树受该 provider 保护;块外路由保持公开;父块认证对子节点继承,新增子节点放在块内才受保护。

概念解释

认证挂载点决定保护边界。按业务域划分子树:公开接口在块外,受保护接口在块内。块内可再嵌套分组与额外授权拦截,结构清晰便于回归受保护面。

原理流程

  1. 安装命名 provider。
  2. 在 routing 内用 authenticate 块圈定子树。
  3. 子树请求先过认证 provider。
  4. 块外兄弟路由不受影响。

代码或图示

routing {
    get("/health") { /* 公开 */ }
    authenticate("jwt-auth") {
        route("/me") { get { /* 受保护 */ } }
    }
}

常见误区

  • 新接口加在块外:漏保护。
  • 认证块包过公开文档接口:被拦截无法访问。

追问

  • 嵌套 authenticate 会叠加校验吗?答:按组合规则生效,具体行为见多认证题目。
  • 节点级认证能继承到孙节点吗?答:块内子树继承。

06.8.1.2-034 authenticate 块内能否混合公开接口?

一句话结论

认证块默认保护块内全部路由;需要公开的特例应放到块外,或使用可选认证/匿名放行机制;把公开接口塞进受保护块再逐个放行,规则缠绕且容易遗漏。

概念解释

结构上应让认证边界与业务边界一致。少数匿名可访问的接口应在路由树中独立成公开分支。若框架支持可选认证,可在同一处理器内区分有无主体,但不要把强制保护与公开混写。

原理流程

  1. 划分强制认证与公开路由。
  2. 公开路由注册在认证块外。
  3. 需区分场景用可选认证。
  4. 回归两组路径断言状态码。

代码或图示

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 里写拒绝响应。消息区分可读的中性提示,细节留在服务端日志。

原理流程

  1. 定义统一错误响应结构。
  2. challenge 按失败类型填状态码与错误码。
  3. 日志记录具体原因与主体标识。
  4. 各 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 类型便于下游授权;不同类型主体需在读取时区分。组合顺序影响挑战响应的生成。

原理流程

  1. 在安装器内定义多个命名 provider。
  2. 认证块引用多个名称。
  3. 请求按策略逐个尝试校验。
  4. 通过则写主体,失败汇总触发 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;强制保护接口必须用普通认证块。

原理流程

  1. 配置可选 provider:凭据缺失不拒绝。
  2. 凭据有效解析主体写入 Call。
  3. Handler 读取可空主体分支处理。
  4. 凭据无效(非缺失)按策略决定拒绝还是忽略。

代码或图示

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 释放。

原理流程

  1. provider 构造 principal 并写入。
  2. Handler 按类型读取。
  3. 授权层基于主体判定权限。
  4. 业务服务接收主体标识作为入参。

代码或图示

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。

原理流程

  1. 模块装配期安装认证插件并定义 provider。
  2. 路由树注册受保护块并引用名称。
  3. 请求先过认证拦截,再进 Handler。
  4. 未通过 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 误用后果严重。核对路径:编译告警 -> 迁移指南 -> 官方认证文档 -> 测试验证。答案中应能说出需要核对的维度,而不是编造精确类名。

原理流程

  1. 编译收集弃用与 unresolved 告警。
  2. 对照迁移指南替换 provider 与主体读取写法。
  3. 回归匿名、无效、有效三类请求。
  4. 核对挑战响应与状态码行为。

代码或图示

核对清单: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 版本兼容。

原理流程

  1. 安装 JWT 插件并配置校验参数。
  2. validate 回调读取 Claims 构造主体。
  3. 路由块引用 JWT provider。
  4. 请求携带令牌,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。

原理流程

  1. 提取并解析令牌结构。
  2. 用匹配密钥/公钥验证签名。
  3. 校验 exp、iss、aud 与自定义声明。
  4. 通过后映射 principal,否则拒绝。

代码或图示

校验顺序:签名 -> exp -> iss -> aud -> 自定义声明 -> 主体映射

常见误区

  • 不校验 iss/aud:别的系统签发的令牌可复用。
  • 过期容忍时间不明确:时钟漂移与撤销窗口处理混乱。

追问

  • 时钟漂移怎么处理?答:配置有限的过期容忍窗口,具体值按安全基线。
  • 声明缺失算什么失败?答:按未认证或无权限处理,不进入业务。

06.8.1.2-043 JWT 密钥与算法如何配置?

一句话结论

对称算法用共享密钥,非对称算法用公钥验签(私钥仅在签发侧);算法固定在白名单,不接受令牌头指定的任意算法;密钥按环境隔离并支持轮换,不写进代码仓库。

概念解释

HS256 等对称算法验签与签发共用密钥,泄露即可伪造;RS256 等非对称算法服务端只持公钥。算法混淆攻击利用头声明改算法类型,因此服务端强制配置算法而非信任令牌头。

原理流程

  1. 选定算法与密钥类型。
  2. 服务端配置验签密钥/公钥。
  3. 固定允许的算法白名单。
  4. 密钥经环境变量/密钥管理注入,支持轮换。

代码或图示

对称:密钥两端共享,保管要求高
非对称:服务端持公钥验签,私钥隔离在签发侧

常见误区

  • 允许 alg: none 或任意算法:签名校验可被绕过。
  • 密钥硬编码进配置仓库:泄露后无法快速轮换。

追问

  • 待确认:JWT 验证器密钥与算法配置字段,以插件文档核对。
  • 密钥轮换怎么做?答:过渡期双密钥验签,新签发用新密钥,旧密钥逐步下线。

06.8.1.2-044 Claims 如何映射为 principal?

一句话结论

validate 回调从已验签的 payload 读取 subject、角色、租户等声明,构造类型化 principal;读取缺失声明时返回 null 拒绝认证;主体不保留原始令牌与敏感明文。

概念解释

映射是 JWT 到应用身份模型的转换层:声明名与应用主体字段对应。转换失败(声明缺失、格式非法)按认证失败处理。principal 携带授权所需的最小信息集。

原理流程

  1. 验签通过后进入 validate。
  2. 读取标准与自定义声明。
  3. 校验必要声明存在并构造主体。
  4. 失败返回 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 时走刷新流程,刷新失败再重新登录。

原理流程

  1. 访问令牌过期,provider 拒绝并返回 401。
  2. 客户端用刷新令牌调用刷新接口。
  3. 服务端校验刷新令牌,签发新访问令牌。
  4. 刷新令牌轮换或失效后要求重新登录。

代码或图示

访问令牌(短时效,无状态)
刷新令牌(可吊销,服务端记录或受控存储)

常见误区

  • 访问令牌设很长有效期:泄露后长期可用。
  • 刷新令牌不过期、不可吊销:泄露后无法收回。

追问

  • 待确认:所用 JWT 库与 Ktor 插件对过期令牌的异常/响应处理,以文档核对。
  • 多端登录刷新如何管理?答:按设备/会话记录刷新令牌,支持单点吊销。

06.8.1.2-046 JWT 撤销与黑名单怎么做?

一句话结论

无状态 JWT 本身无法主动失效;需要撤销时引入黑名单(登出、改密、强制下线的令牌标识存入缓存并设剩余有效期),或缩短访问令牌有效期配合刷新令牌吊销;黑名单查询在认证阶段完成。

概念解释

撤销场景:用户登出、密码变更、权限回收、安全下线。黑名单记录 jti 或用户会话标识,TTL 不超过令牌剩余有效期,避免无限增长。高并发下黑名单存储需低延迟,命中即拒绝。

原理流程

  1. 登出/下线时把令牌 jti 或会话标识写入黑名单。
  2. 认证校验签名与声明后,查黑名单。
  3. 命中拒绝,否则放行。
  4. 条目随令牌过期自动清除。

代码或图示

// 伪流程:验签通过后检查黑名单
if (blacklist.contains(jti)) return@validate null

常见误区

  • 认为 JWT 登出即失效:客户端删令牌,服务端无状态,令牌在过期前仍可用。
  • 黑名单永久保存:存储膨胀。

追问

  • 黑名单存哪里?答:Redis 等低延迟缓存,按 TTL 清理;规模与可用性按部署评估。
  • 待确认:Ktor 认证阶段接入远程黑名单的位置与阻塞约束,以实现核对。

06.8.1.2-047 不验签直接读 payload 有什么风险?

一句话结论

未验签的 payload 可被任意伪造:攻击者篡改 subject、角色等声明冒充身份;Base64 解码不等于校验,任何把解码内容当可信身份的做法都是严重漏洞。

概念解释

JWT 三段中签名只防篡改,payload 本身可读。信任决策(用户是谁、有无权限)必须建立在验签通过之后。调试时解码 payload 看内容可以,业务认证绝不能走解码直读。

原理流程

  1. 攻击者修改 payload 中身份/角色声明。
  2. 重新编码但不补有效签名(或用 none 算法)。
  3. 服务端若直读 payload 即信任伪造内容。
  4. 越权或冒充身份成功。

代码或图示

错误:decode(payload) -> 取 userId -> 放行
正确:verify(签名) -> 校验声明 -> 映射主体

常见误区

  • 以为 payload 加密了:实际只是编码。
  • 调试代码残留在生产认证路径:伪造入口。

追问

  • 如何代码审计发现这类问题?答:搜索令牌解码调用点,确认其下游没有做验签与身份决策。
  • 待确认:所用 JWT 库是否分离解码与验签 API,以库文档核对。

06.8.1.2-048 算法混淆攻击如何防范?

一句话结论

服务端固定允许的签名算法白名单,不信任令牌头中的 alg;非对称场景不把公钥当对称密钥使用;验签配置明确算法,库默认拒绝 none 算法。

概念解释

算法混淆诱导服务端用错误密钥或算法验证签名(如把 RS256 当 HS256,用公钥当 HMAC 密钥)。防御核心:算法由服务端配置决定,密钥类型与算法匹配,库配置关闭不安全算法。

原理流程

  1. 服务端配置固定算法与对应密钥。
  2. 验签按配置算法执行,忽略令牌头算法声明。
  3. 密钥类型与算法一致。
  4. 未知/拒绝算法直接失败。

代码或图示

服务端配置:alg = RS256,验签公钥
令牌头 alg 仅作参考,不改变服务端策略

常见误区

  • 按令牌头 alg 选择验签方式:策略被攻击者控制。
  • 非对称公钥误用于 HMAC 校验:密钥材料泄露面被滥用。

追问

  • 待确认:JWT 库是否默认限制算法列表,以库安全文档核对。
  • 多算法兼容期怎么过渡?答:按系统约定逐步收敛到单一算法。

一句话结论

API 调用常用 Authorization Bearer 头,由前端代码主动携带;浏览器站点可用 HttpOnly Cookie 存储令牌防 XSS 窃取;两种方式各有风险面,选择按调用形态与防护能力决定。

概念解释

Bearer 头不受 Cookie 自动携带影响,适合 SPA 与开放 API;Cookie 方式减少 JS 读取令牌的暴露面,但需防 CSRF。令牌存放位置还要配合传输加密、过期策略与存储安全。

原理流程

  1. 调用形态:前后端分离 API -> 头;浏览器站点 -> Cookie。
  2. Cookie 设 HttpOnly、Secure、SameSite。
  3. 传输全程 HTTPS。
  4. 令牌有效期与刷新策略配套。

代码或图示

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、自定义业务头)要在预检响应中声明允许,否则浏览器拦截。

原理流程

  1. 服务端配置允许来源(精确域,非通配)。
  2. 声明允许方法与请求头。
  3. 凭据模式开启时配置对应标志。
  4. 浏览器预检通过后发实际请求。

代码或图示

install(CORS) {
    // 来源精确配置;allowCredentials 与来源规则以插件文档为准
    anyMethod()
    header("Authorization")
}

常见误区

  • 凭据模式下来源用 *:浏览器拒绝携带凭据。
  • 漏加允许头:Authorization 在预检后被拦截。

追问

  • 待确认:Ktor CORS 插件凭据配置项名称,以官方文档核对。
  • 跨域 Cookie 还要注意什么?答:SameSite、Domain、Path 属性与站点方案匹配。

06.8.1.2-051 多租户/多受众 JWT 如何校验?

一句话结论

令牌声明中携带租户或受众标识,接口校验当前请求匹配的租户/受众;多租户系统还要在授权与数据查询层按租户隔离,不能只靠令牌声明信任数据归属。

概念解释

audience 限定令牌适用的 API 系统,tenant 限定所属租户。校验在认证阶段完成声明匹配,数据层按租户条件过滤。租户标识从已验签主体取,不接受请求参数覆盖。

原理流程

  1. 令牌签发时带 aud 与 tenant 声明。
  2. 认证 provider 校验 aud/tenant 与当前服务匹配。
  3. principal 携带租户标识。
  4. 业务查询按租户隔离条件过滤。

代码或图示

// 校验示意:声明匹配当前租户
if (principal.tenant != currentTenant) {
    call.respond(HttpStatusCode.Forbidden)
}

常见误区

  • 用请求头/参数传租户覆盖令牌声明:越权跨租户。
  • 认证过了就不做数据层隔离:水平越权。

追问

  • 多租户令牌跨服务复用吗?答:audience 限定服务范围,跨服务需重新签发或明确信任关系。
  • 待确认:Claim 中租户字段的类型与缺失处理,以实现核对。

06.8.1.2-052 JWT 插件的坐标与配置项需要核对哪些点?

一句话结论

接入前核对:插件/库 Maven 坐标与 Ktor、Kotlin 版本兼容,验证器配置字段(密钥、算法、issuer、audience、过期容忍),主体回调签名;不确定坐标标待确认并查官方文档与依赖仓库。

概念解释

版本不兼容会出现编译告警或运行期验签异常。核对清单包括依赖坐标、配置对象属性名、回调入参类型、异常类型。不要在答案里编造未核实的版本号与坐标。

原理流程

  1. 查官方文档确认 JWT 方案与依赖坐标。
  2. 对齐 Ktor/Kotlin 基线版本。
  3. 逐字段核对验证器配置。
  4. 用有效、过期、伪造令牌三类用例验证。

代码或图示

核对清单:依赖坐标 / 版本兼容 / 验证器字段 / 回调签名 / 异常类型

常见误区

  • 凭记忆写坐标:版本与库名可能已变。
  • 只测有效令牌:过期与伪造路径未验证。

追问

  • 待确认:Ktor 3 JWT 插件确切坐标与配置属性,以 ktor.io 文档与依赖仓库为准。
  • 验签失败抛什么异常?答:以库实现为准,认证插件转换为 challenge 响应。

06.8.1.2-053 Session 认证模型与 JWT 有什么区别?

一句话结论

Session 在服务端保存会话状态,客户端只持有会话标识;JWT 自包含声明,服务端不保存会话状态。Session 可即时吊销,JWT 撤销依赖黑名单或短时效;选型看会话管理需求与部署形态。

概念解释

Session 标识(Session ID)本身无意义,状态在服务端;令牌载荷可被客户端解码。Session 适合传统浏览器与需要主动下线的场景,JWT 适合开放 API 与跨服务无状态传递。两者都依赖 HTTPS 保护凭据。

原理流程

  1. 登录成功服务端创建会话,返回会话标识。
  2. 后续请求携带标识,服务端查会话状态。
  3. 会话可主动删除/失效。
  4. 对比 JWT:声明在令牌内,服务端验签后信任。

代码或图示

Session:ID -> 服务端存储(可吊销)
JWT:自包含声明 -> 验签信任(撤销需配套机制)

常见误区

  • 把 Session ID 当令牌信任内容:状态以服务端存储为准。
  • 认为无状态就完全不需要撤销:泄露令牌仍需限制影响。

追问

  • 待确认:Ktor Session 插件的存储与 Cookie 配置 API,以官方文档核对。
  • 混合方案可行吗?答:可在服务端会话基础上加短期访问令牌,按场景组合。

06.8.1.2-054 服务端 Session 如何存储?

一句话结论

会话数据存服务端存储(内存、Redis 或数据库),客户端只持标识;多实例部署用共享存储,内存存储仅适合单实例;存储设过期、淘汰与序列化兼容策略。

概念解释

内存会话重启即失且不能多实例共享;Redis 等共享存储支持集群与会话过期。会话数据最小化:只存必要标识与引用,敏感信息不进会话体。存储访问需低延迟,认证阶段同步读取要控制超时。

原理流程

  1. 登录创建会话,生成标识。
  2. 会话数据写入存储并设 TTL。
  3. 请求携带标识,存储读取会话。
  4. 登出或过期清除会话。

代码或图示

单实例:内存 Map(重启丢失)
多实例:共享缓存/数据库(按标识读写,带 TTL)

常见误区

  • 多实例用内存会话:请求落到不同实例状态丢失。
  • 会话体存大对象:存储与读取成本上升。

追问

  • 待确认:Ktor Session 插件是否提供服务端会话存储适配器,以文档核对;多数场景需自接共享存储。
  • 会话存储故障怎么办?答:降级策略与超时控制,避免认证阶段阻塞。

一句话结论

会话 Cookie 设 HttpOnly 防脚本读取、Secure 限 HTTPS、SameSite 防跨站自动携带,Path/Domain 收敛作用域;标识不可预测,过期与滑动策略明确;敏感会话不通过 URL 传递。

概念解释

Cookie 属性决定泄露与滥用面:HttpOnly 降低 XSS 窃取风险,Secure 防明文传输,SameSite 缓解 CSRF。会话标识需高熵随机,不能自包含可解码信息。Cookie 名称与作用域按站点约定收敛。

原理流程

  1. 登录成功下发会话 Cookie。
  2. 设置安全属性与作用域。
  3. 浏览器后续请求自动携带。
  4. 登出清除 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 有效但服务端会话已清除的情况。

原理流程

  1. 登录设定绝对有效期。
  2. 活动请求时按滑动策略续期。
  3. 空闲超过阈值清除会话。
  4. 存储与 Cookie 过期时间同步更新。

代码或图示

绝对上限:最长会话时长
滑动续期:每次活动延长,但不超过上限
空闲超时:无活动即失效

常见误区

  • 只续 Cookie 不续服务端 TTL:会话中途消失。
  • 滑动无限续期:被盗会话长期有效。

追问

  • 待确认:Ktor Session 插件是否内置滑动过期支持,以文档核对;否则在拦截层续期。
  • 敏感操作重认证怎么做?答:记录最近认证时间,超阈值要求重新登录。

06.8.1.2-057 会话固定攻击如何防范?

一句话结论

登录成功后重新生成会话标识,废弃登录前的匿名标识;标识高熵随机;登出与权限变更时轮换标识;不接受客户端预设的会话 ID。

概念解释

会话固定是攻击者预置或获取一个会话 ID,待受害者登录后复用该标识提权。防御关键是认证状态变化时标识轮换:匿名 -> 登录、普通 -> 提权都换新 ID,旧 ID 失效。

原理流程

  1. 匿名阶段标识仅用于临时状态。
  2. 登录成功生成新标识,迁移必要会话数据。
  3. 旧标识作废。
  4. 提权/改密再次轮换。

代码或图示

登录前 ID -> 登录成功:换新 ID,旧 ID 失效

常见误区

  • 登录前后使用同一 ID:攻击者预置 ID 即可复用。
  • 标识可预测:被枚举或猜测。

追问

  • 待确认:Ktor Session 插件是否支持标识轮换 API,以文档核对;否则在登录流程重建会话。
  • 会话数据迁移怎么办?答:新会话复制必要数据,旧会话删除。

06.8.1.2-058 分布式部署下 Session 如何共享?

一句话结论

会话状态存入多实例可访问的共享存储(Redis 等),实例只保留标识解析能力;会话复制需考虑一致性、过期与故障降级;不要用各实例内存会话拼凑分布式状态。

概念解释

共享存储解决实例间会话可见性。读写延迟影响认证响应,需超时与降级策略;会话序列化要兼容版本演进。会话粘滞可作为过渡,但不替代共享存储,实例重启仍丢状态。

原理流程

  1. 会话写入共享存储并设 TTL。
  2. 任意实例读取标识对应会话。
  3. 更新会话回写存储。
  4. 存储故障按降级策略处理。

代码或图示

实例 A/B/C -> 共享会话存储(Redis)

常见误区

  • 靠会话粘滞规避共享存储:扩容重启仍丢状态。
  • 会话对象直接序列化进不兼容格式:版本升级后反序列化失败。

追问

  • 待确认:共享存储适配器与序列化方式,按所选库实现核对。
  • 会话读取超时怎么办?答:有限超时,失败按未认证或降级策略,不无限阻塞。

06.8.1.2-059 Session 序列化有哪些注意事项?

一句话结论

会话对象字段稳定、类型明确,避免序列化不兼容的复杂对象;版本演进时字段增删保持兼容;敏感数据不进会话体;跨语言共享存储时选用通用编码格式。

概念解释

会话在重启、扩容、版本升级后仍需可读取。序列化失败表现为登录态丢失或反序列化异常。会话体应是简单数据结构,引用的服务对象不应直接存入会话。

原理流程

  1. 定义简单会话数据类。
  2. 字段变更保持向后兼容。
  3. 序列化格式与存储匹配。
  4. 升级前验证旧会话可读取或明确清除策略。

代码或图示

data class SessionState(val userId: String, val issuedAt: Long)

常见误区

  • 把业务实体引用存会话:生命周期与序列化双重问题。
  • 字段类型直接改窄/改删:旧会话反序列化失败。

追问

  • 待确认:Ktor Session 插件默认序列化方式与可替换编码器,以文档核对。
  • 旧版本会话如何处理?答:升级时清除或做兼容反序列化,按发布策略决定。

06.8.1.2-060 什么时候选 Session,什么时候选 Token?

一句话结论

传统浏览器站点、需要即时吊销与集中会话管理选 Session;开放 API、跨服务传递、无状态部署选 Token;按客户端形态、撤销需求、生态集成与团队经验综合决策,可混合使用。

概念解释

决策维度:客户端能否安全存 Cookie、撤销时效要求、多服务信任关系、部署无状态程度。Session 服务端有状态,Token 依赖有效期与配套撤销机制。没有绝对优劣,匹配场景即可。

原理流程

  1. 梳理客户端形态与凭据存储能力。
  2. 确认撤销与多端管理需求。
  3. 评估服务端状态与部署模型。
  4. 选定方案并配套防护措施。

代码或图示

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)通过转换器接入。

原理流程

  1. 安装插件并注册各类型转换器。
  2. 请求进入:按 Content-Type 选反序列化器读取 body。
  3. Handler 操作类型化对象。
  4. 响应:按 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 时按默认转换器响应;服务端不支持期望类型应明确失败,而不是偷偷换格式。

原理流程

  1. 读取请求 Content-Type 匹配反序列化转换器。
  2. 读取 Accept 列表匹配响应序列化器。
  3. 匹配成功走对应编解码。
  4. 无匹配:返回不支持类型或默认行为。

代码或图示

请求: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 原生序列化方案,配合编译期插件生成序列化器。配置项覆盖未知键忽略、默认值编码、命名策略、宽松解析等。数据类与枚举需可序列化,第三方类型需自定义序列化器。

原理流程

  1. 引入序列化依赖并对齐 Kotlin 版本。
  2. 配置 Json 实例。
  3. 安装 ContentNegotiation 注册 json 转换器。
  4. 数据类标注后 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 下需模块支持处理默认值与空值。

原理流程

  1. 评估既有生态与依赖体积。
  2. 选定方案并配置映射规则。
  3. 注册对应转换器。
  4. 统一 DTO 风格与配置。

代码或图示

install(ContentNegotiation) {
    jackson {
        // ObjectMapper 配置:命名策略、日期、空值等
    }
}

常见误区

  • 同一服务同时挂两套 JSON 转换器:行为不确定且依赖膨胀。
  • Jackson 未注册 Kotlin 模块:数据类构造与默认值解析异常。

追问

  • 待确认:Ktor 3 Jackson 转换器依赖与 ObjectMapper 配置入口,以文档核对。
  • 多平台项目倾向哪个?答:kotlinx.serialization 多平台支持更自然,按目标平台评估。

06.8.1.2-065 序列化配置有哪些常见项?

一句话结论

常见配置:忽略未知键、是否编码默认值、空值处理、日期/时间格式、命名策略、枚举大小写、宽松数字解析;配置在客户端与服务端之间保持一致,避免字段丢失或解析失败。

概念解释

忽略未知键提升前后端版本兼容;默认值编码影响报文大小;日期格式需统一时区与格式。配置项按所选序列化库 API 落地,不要假设两套库配置同名。

原理流程

  1. 确定兼容策略:未知字段、默认值、空值。
  2. 配置时间与命名约定。
  3. 与客户端/其他服务对齐。
  4. 用样例报文验证往返一致。

代码或图示

Json {
    ignoreUnknownKeys = true
    encodeDefaults = false
}

常见误区

  • 严格拒绝未知字段:接口演进时旧客户端被拒。
  • 日期默认格式不统一:跨服务解析偏差。

追问

  • 待确认:各配置项在 kotlinx/Jackson 中的准确属性名,以库文档核对。
  • 枚举前端传字符串怎么配?答:按库配置枚举读取策略,校验非法值。

06.8.1.2-066 请求反序列化失败如何处理?

一句话结论

body 格式错误、字段缺失或类型不符属于客户端错误,应映射 400 与统一错误结构;异常在插件或 StatusPages 层捕获,记录报文特征(不含敏感内容),不把解析堆栈返回给客户端。

概念解释

反序列化异常分语法错误与语义错误:JSON 不合法、类型不匹配、必填缺失。失败响应指出字段与原因有助于客户端修正,但不暴露内部类名与堆栈。配置上可放宽未知键,必填与类型仍严格校验。

原理流程

  1. 转换器反序列化抛出异常。
  2. 异常进入状态页/插件处理器。
  3. 映射 400 与字段级错误信息。
  4. 日志记录异常与 trace 标识。

代码或图示

install(StatusPages) {
    // 捕获反序列化异常,返回 400 统一结构;异常类型以所用库为准
}

常见误区

  • 解析异常变成 500:客户端错误被当系统故障。
  • 响应回显完整堆栈与类名:泄露内部结构。

追问

  • 待确认:反序列化异常的具体类型层次,以序列化库实现核对。
  • 字段级错误列表怎么返回?答:在错误结构中带字段与原因,按 API 约定。

06.8.1.2-067 响应序列化失败如何处理?

一句话结论

响应对象存在不可序列化字段、循环引用或类型不支持时,序列化在写出阶段失败;应在测试中覆盖响应 DTO 可序列化,失败兜底 500 并记录,响应不被客户端看到残缺 body。

概念解释

响应序列化问题多为 DTO 设计:暴露不可序列化类型、双向关联循环引用、日期类型未配置。发布前用样例对象走一遍序列化;运行期失败要保证响应状态与 body 不矛盾。

原理流程

  1. Handler 产出响应对象。
  2. 转换器序列化时发现不支持结构。
  3. 异常被兜底处理,记录对象类型与字段。
  4. 返回中性错误响应。

代码或图示

预防:DTO 只用基础类型与可序列化数据类,关联关系扁平化

常见误区

  • 直接把领域实体当响应 DTO:内部结构与循环引用外泄。
  • 序列化失败后仍声称 200:body 残缺或为空。

追问

  • 待确认:写出阶段序列化异常的捕获时机,以插件实现核对。
  • 循环引用怎么避免?答:响应 DTO 单向扁平化,不返回实体图。

06.8.1.2-068 自定义 Converter 如何注册?

一句话结论

实现对应媒体类型的编解码契约,在 ContentNegotiation 安装时按类型注册;用于非 JSON 格式(表单、自定义文本、二进制)或需要定制编解码规则的场景;注册后 receive/respond 按类型选用。

概念解释

转换器负责对象与报文之间的双向映射:反序列化读字节构造对象,序列化写对象写字节与媒体类型。自定义转换器要处理空 body、非法格式与异常抛出规则,与框架异常处理衔接。

原理流程

  1. 定义转换器实现编解码接口。
  2. 指定支持的媒体类型。
  3. install 时注册到协商插件。
  4. 请求/响应按媒体类型匹配调用。

代码或图示

Converter:
- read(contentType, body): 对象
- write(contentType, obj): body + 头

常见误区

  • 只实现一个方向:另一方向无人处理。
  • 自定义编解码不抛规范异常:错误状态难以映射。

追问

  • 待确认:Ktor 3 转换器接口与注册方法签名,以官方文档核对。
  • 多版本格式共存怎么办?答:按媒体类型区分转换器,版本协商在类型上表达。

06.8.1.2-069 文本、HTML、二进制响应与内容协商是什么关系?

一句话结论

纯文本/HTML 由 respondText、respondBytes 等基础能力直接写出并设置媒体类型,不经过对象 JSON 转换器;内容协商主要针对结构化对象编解码;二进制下载要正确设置 Content-Type 与长度/流式策略。

概念解释

区分响应形态:字符串与字节直接响应,对象才序列化。HTML 模板渲染、文件下载、字节流各走对应响应 API。媒体类型错误会导致客户端解析行为异常(下载变成展示等)。

原理流程

  1. 判断响应形态:文本/字节/结构化对象。
  2. 文本与字节用基础响应 API。
  3. 对象走协商转换器。
  4. 设置正确 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 模块版本。项目内统一版本管理,不各处引入不同大版本。

原理流程

  1. 对齐 Ktor 与 Kotlin 基线。
  2. 查官方文档确认转换器坐标。
  3. 锁定序列化库兼容版本。
  4. 用往返报文测试验证。

代码或图示

核对矩阵:Ktor / Kotlin / kotlinx-serialization 或 Jackson 模块版本

常见误区

  • 凭记忆写依赖版本:与基线不兼容。
  • 服务端与客户端序列化库版本差距过大:格式细节不一致。

追问

  • 待确认:Ktor 3 各序列化转换器的确切坐标与推荐版本,以 ktor.io 文档为准。
  • 升级序列化库先测什么?答:往返兼容、默认值与空值、日期格式。

06.8.1.2-071 CORS 插件解决什么问题?

一句话结论

CORS 插件按浏览器跨域规则附加响应头,声明允许的来源、方法、头与凭据;它只管理浏览器侧跨域限制,不替代服务端认证与网络层访问控制。

概念解释

浏览器出于同源策略限制跨域读取,服务端通过 CORS 响应头告知浏览器哪些跨域调用被允许。预检请求(OPTIONS)与实际请求分别处理。CORS 放行不等于信任调用方,认证仍需独立完成。

原理流程

  1. 浏览器发起跨域请求或预检。
  2. 插件匹配来源与请求方法/头。
  3. 追加 CORS 响应头。
  4. 浏览器据此决定是否放行脚本读取响应。

代码或图示

install(CORS) {
    anyMethod()
    header("Authorization")
    // 来源按精确域配置
}

常见误区

  • 把 CORS 当鉴权:放通来源后仍需认证。
  • 公网服务随意允许所有来源:扩大跨域滥用面。

追问

  • 待确认:Ktor 3 CORS 插件配置项名称,以官方文档核对。
  • 非浏览器调用受 CORS 约束吗?答:不受浏览器策略约束,仍按服务端安全规则控制。

06.8.1.2-072 允许来源、方法、头如何配置?

一句话结论

来源用精确域名列表或匹配规则配置,方法按需枚举,请求头与暴露头分别声明;不要在凭据模式下用通配来源;配置最小必要集合,定期复审。

概念解释

允许方法控制跨域可调用的 HTTP 动词;允许请求头决定预检可携带的自定义头;暴露头决定脚本可读的响应头。配置过宽等于放松浏览器侧限制,收窄到业务所需范围。

原理流程

  1. 列出前端站点来源清单。
  2. 枚举接口使用的方法。
  3. 声明自定义请求头与需暴露的响应头。
  4. 按环境区分开发与生产配置。

代码或图示

Allow-Origin: 精确来源列表
Allow-Methods: GET, POST, ...
Allow-Headers: Authorization, Content-Type
Expose-Headers: 自定义响应头

常见误区

  • 允许头漏加 Authorization:带令牌跨域请求被预检拦截。
  • 来源规则过宽:非信任站点可跨域读取。

追问

  • 待确认:来源匹配正则/前缀配置方式,以插件文档核对。
  • 开发环境能放开来源吗?答:可仅在开发环境放宽,生产必须精确配置。

06.8.1.2-073 预检 OPTIONS 请求如何处理?

一句话结论

CORS 插件自动响应预检 OPTIONS:根据请求头与方法返回允许信息并短路;业务 Handler 不应自行处理预检;预检通过后浏览器才发送实际请求。

概念解释

预检发生在实际请求前,浏览器询问服务端是否允许该来源、方法、自定义头。插件生成 OPTIONS 响应,不进入业务逻辑。预检缓存可减少重复询问,缓存时间按插件配置。

原理流程

  1. 浏览器发送 OPTIONS 预检,带来源、方法、头。
  2. 插件匹配配置并返回 CORS 头。
  3. 预检通过,发送实际请求。
  4. 预检失败,浏览器阻止实际请求发出。

代码或图示

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 要求不同。

原理流程

  1. 配置精确允许来源。
  2. 开启凭据允许标志。
  3. 配套 Cookie 安全属性。
  4. 按 CSRF 防护方案校验跨站请求。

代码或图示

凭据模式:Allow-Origin 精确 + Allow-Credentials: true
禁止:Origin: * 与凭据同时使用

常见误区

  • 图省事来源设通配:浏览器拒绝携带凭据。
  • 开了凭据却不做 CSRF 防护:跨站请求可被利用。

追问

  • 待确认:Ktor CORS 凭据配置属性名,以官方文档核对。
  • Bearer 令牌跨域需要凭据标志吗?答:头携带方式不同,凭据标志针对 Cookie 自动携带场景。

06.8.1.2-075 Compression 插件如何选择编码器?

一句话结论

压缩插件按请求 Accept-Encoding 与响应内容选择编码器(gzip/deflate 等,具体支持列表以版本为准);可配置编码优先级与排除条件;对已压缩内容(图片、视频、压缩包)不再二次压缩。

概念解释

压缩在响应写出阶段包裹:根据客户端支持的编码与响应类型挑选编码器。编码器选择受内容大小、类型与配置影响;压缩占用 CPU,解压在客户端,需权衡延迟与带宽。

原理流程

  1. 请求携带 Accept-Encoding。
  2. 插件匹配可用编码器。
  3. 响应内容满足压缩条件则编码并设 Content-Encoding。
  4. 不满足条件按原内容写出。

代码或图示

install(Compression) {
    gzip { /* 最小大小等配置 */ }
}

常见误区

  • 对已是压缩格式的文件再压缩:CPU 浪费且收益很小。
  • 不核对支持的编码器列表:按记忆写可能不被支持。

追问

  • 待确认:Ktor 3 Compression 支持的编码器与配置 DSL,以官方文档核对。
  • 压缩阈值怎么定?答:小文本不压缩,按内容类型与大小配置最小阈值。

06.8.1.2-076 压缩对哪些响应生效,如何排除?

一句话结论

可按内容类型、大小与响应条件排除:静态压缩资源、流式下载、实时日志等场景可不压缩;排除规则在插件配置中声明,避免对不该压缩的内容强行编码。

概念解释

排除维度:媒体类型、报文大小、响应形态。动态 JSON/文本通常收益明显;已压缩二进制与大文件传输不适合 CPU 压缩。压缩插件与缓存插件配合时注意缓存键是否含编码信息。

原理流程

  1. 列出响应类型与大小分布。
  2. 配置可压缩类型与最小阈值。
  3. 排除二进制与流式场景。
  4. 压测观察 CPU 与带宽收益。

代码或图示

压缩:JSON、文本、HTML
排除:图片、视频、压缩包、部分流式响应

常见误区

  • 全量压缩不设阈值:小报文压缩反而增大体积。
  • 代理缓存未区分编码:解压版本被错误缓存。

追问

  • 待确认:排除条件配置方式(类型/大小),以插件文档核对。
  • 压缩与响应包装插件顺序?答:先包装生成内容,再压缩写出,顺序按管道阶段确认。

06.8.1.2-077 ConditionalHeaders 协商缓存如何工作?

一句话结论

ConditionalHeaders 根据响应资源生成 Last-Modified/ETag 校验头,客户端带 If-Modified-Since/If-None-Match 请求时未变化返回 304,避免重复传输 body。

概念解释

协商缓存让客户端在资源未变时只收状态码。ETag 是资源版本标识,Last-Modified 是时间戳。校验依赖可稳定计算资源版本;动态易变内容不适合强协商缓存。

原理流程

  1. 首次响应携带 ETag/Last-Modified。
  2. 后续请求带校验头。
  3. 插件/处理器比对资源版本。
  4. 未变化返回 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 控制浏览器与共享代理缓存行为。指令选择看资源可公开性与版本化程度:带内容哈希的资源可长缓存,接口响应默认不缓存,用户相关响应必须私有。

原理流程

  1. 区分资源类型与敏感性。
  2. 按类型配置缓存指令与时长。
  3. 响应写出头。
  4. 客户端/代理按指令缓存。

代码或图示

install(CachingHeaders) {
    // 按响应类型配置 Cache-Control;具体 DSL 以文档为准
}

常见误区

  • 接口响应被共享缓存:其他用户拿到缓存数据。
  • 未版本化资源长缓存:发版后客户端拿旧文件。

追问

  • 待确认:CachingHeaders 插件配置方式与可用指令,以官方文档核对。
  • 敏感响应加什么指令?答:private + no-cache 或短 max-age,按安全基线。

06.8.1.2-079 静态与动态响应的缓存策略有何差异?

一句话结论

静态资源可版本化后长缓存并配合协商缓存;动态接口响应按用户私有或不缓存,缓存键包含主体与必要维度;缓存策略在网关、服务端与客户端三层保持一致。

概念解释

静态资源内容固定、可按文件名版本化;动态响应随主体、时间、权限变化。错误响应与鉴权响应不应被共享缓存。缓存分层:浏览器、代理 CDN、服务端缓存各自策略明确。

原理流程

  1. 静态资源:文件名带哈希,长 max-age + 不可变。
  2. 动态响应:私有或 no-cache。
  3. 共享缓存场景按主体与参数构造键。
  4. 失效与发布策略配套。

代码或图示

静态:/assets/app.<hash>.js -> 长缓存
动态:/api/me -> 私有 / 不缓存

常见误区

  • 动态列表接口被 CDN 共享缓存:串用户数据。
  • 静态资源不版本化:长缓存导致陈旧。

追问

  • 待确认:服务端缓存头与代理缓存的配合规则,按部署架构核对。
  • 缓存失效怎么做?答:版本化文件名或主动失效,按发布流程。

06.8.1.2-080 响应头插件之间的顺序有什么影响?

一句话结论

压缩、缓存、CORS、自定义头插件按管道层次包裹:内容生成在前,压缩与头补充在后;顺序错误可能导致头被覆盖、压缩作用于错误内容;调整后用实际响应报文核对头集合。

概念解释

各插件写入不同响应头,但包裹层次决定谁先谁后。CORS 头需对预检与实际响应都生效;缓存头与压缩编码应共存不冲突。装配顺序按「生成内容 -> 协商/缓存 -> 压缩 -> 补充安全头」梳理。

原理流程

  1. 梳理各插件写入的头与处理阶段。
  2. 按内容生成到写出的顺序安装。
  3. 用样例请求观察最终响应头。
  4. 冲突时明确各插件职责边界。

代码或图示

内容序列化 -> 缓存/协商头 -> 压缩编码 -> CORS/安全头

常见误区

  • 多个插件重复写同一头:后写覆盖先写。
  • 压缩在缓存头之前处理:缓存键未考虑编码。

追问

  • 待确认:各响应插件在 Ktor 3 中的默认阶段,以官方文档核对。
  • 头冲突如何排查?答:抓实际响应报文,按插件日志定位写入来源。

06.8.1.2-081 请求参数校验在哪一层做?

一句话结论

路径/查询/表单参数在进入业务服务前由路由层或公共校验器完成类型、格式、范围与必填校验;校验失败短路 400,业务服务只接收已校验类型化值;复杂业务规则在服务层判定。

概念解释

分层校验:输入格式与合法性在入口层,业务一致性与权限规则在服务层。入口校验避免脏数据进入业务逻辑;公共解析器复用规则,减少 Handler 内重复代码。

原理流程

  1. Handler/拦截器读取原始参数。
  2. 公共校验器做类型、格式、范围校验。
  3. 失败返回 400 错误结构。
  4. 合法值传入服务层。

代码或图示

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 但错误码可细分。校验规则集中在公共校验器,保证响应格式一致。

原理流程

  1. 校验器收集字段错误。
  2. 无错误放行;有错误构造错误响应。
  3. 状态码 400,body 带字段错误列表。
  4. 日志记录不包含敏感明文。

代码或图示

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,登录后按用户,内部按租户。存储选择取决于实例数与配额一致性要求;内存快但多实例不准,共享存储一致但有网络开销。

原理流程

  1. 确定限流主体与配额。
  2. 单机或分布式存储选型。
  3. 选择计数算法与窗口。
  4. 超限返回 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 方案不自动携带凭据,攻击面不同。

原理流程

  1. 会话 Cookie 设置 SameSite 与安全属性。
  2. 表单/页面下发 CSRF Token。
  3. 写操作请求携带并校验 Token。
  4. 校验失败拒绝请求。

代码或图示

防护组合:SameSite Cookie + CSRF Token 校验 + 关键操作来源校验

常见误区

  • 只依赖前端隐藏 Token 不在服务端校验:形同虚设。
  • 用 Bearer 令牌却照搬 CSRF 流程:方案不匹配。

追问

  • 待确认:Ktor 生态是否提供 CSRF 插件,以官方/第三方文档核对。
  • 跨站读取风险由什么防?答:CORS 来源限制与认证授权配合。

06.8.1.2-085 XSS 防护的服务端边界是什么?

一句话结论

服务端负责输出编码/转义、设置 Content-Type 与相关安全头、校验输入;最终脚本执行发生在浏览器,前端模板与渲染同样需要转义;服务端不能替代前端渲染层防护。

概念解释

XSS 分存储型、反射型与 DOM 型。服务端可做:响应正确媒体类型、内容安全策略头、入库与输出编码、富文本白名单过滤。DOM 型 XSS 主要在前端渲染链路,服务端输入过滤无法完全覆盖。

原理流程

  1. 输入进入时做格式约束。
  2. 输出按目标上下文(HTML/属性/JS)编码。
  3. 设置 CSP、X-Content-Type-Options 等头。
  4. 富文本走白名单过滤。

代码或图示

服务端:输出编码 / 安全头 / 富文本白名单
前端:模板转义 / 安全 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 误拦业务资源。

原理流程

  1. 梳理站点/接口形态所需头。
  2. 全局拦截器或插件追加响应头。
  3. HTTPS 环境启用 HSTS。
  4. 浏览器与代理行为按头验证。

代码或图示

常用头:
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 需要不同编码。清洗规则过严会破坏正常内容(如富文本)。

原理流程

  1. 输入层:格式校验、非法字符约束、富文本白名单。
  2. 存储:保留原始但受控的数据。
  3. 输出层:按目标上下文编码。
  4. 前端渲染继续转义。

代码或图示

输入:约束与过滤(不替代编码)
输出:HTML / 属性 / JS / URL 各自编码

常见误区

  • 以为入库过滤一次就安全:输出到新上下文仍可能注入。
  • 输出统一当纯文本编码:破坏富文本展示。

追问

  • 特殊字符存不存原始值?答:按业务需要存储,输出时编码,避免不可逆清洗破坏数据。
  • 富文本白名单在哪做?答:服务端过滤标签与事件属性,前端不再执行未过滤 HTML。

06.8.1.2-088 上传与入参大小、类型如何限制?

一句话结论

限制请求体与各部件大小、文件类型与扩展名、字段长度;超限拒绝并释放流;上传目录独立且路径防穿越;大小限制在读取层尽早生效,不在全量入内存后判断。

概念解释

入参限制包括 body 总量、字符串长度、数组/集合上限、上传部件数量与大小。类型校验看内容头与文件头,不仅看扩展名。限制策略防大报文打爆内存、防恶意文件落盘。

原理流程

  1. 声明 body 与部件上限。
  2. 接收过程累计大小,超限中断。
  3. 校验类型、扩展名与内容特征。
  4. 受控落盘或拒绝。

代码或图示

限制项:body 总量 / 字段长度 / 集合大小 / 部件数量 / 文件类型

常见误区

  • 全量读完再判大小:大报文已进内存。
  • 只校验扩展名:伪装类型文件可绕过。

追问

  • 待确认:Ktor 3 请求体大小限制配置入口,以引擎/插件文档核对。
  • 临时文件放哪里?答:独立临时目录,请求结束清理,禁止拼用户输入路径。

06.8.1.2-089 同一子树如何同时支持 JWT 与 Basic?

一句话结论

注册两个命名 provider,认证块同时引用;任一有效凭据即通过,产出统一 principal 类型;下游不区分来源做授权,需要时主体内记录凭据类型;组合策略与挑战行为按版本 API 核对。

概念解释

多方案共存用于同时面向人类后台与机器调用。统一主体模型让授权层一致;不同方案的安全策略(传输、哈希、过期)各自独立。provider 顺序影响挑战响应,不影响通过后的主体结构。

原理流程

  1. 定义 JWT 与 Basic provider。
  2. 认证块引用两个名称。
  3. 请求携带任一有效凭据通过。
  4. 映射为统一 principal 进入业务。

代码或图示

authenticate("jwt-auth", "basic-auth") {
    get("/service") { /* 统一主体 */ }
}

常见误区

  • 两套方案产出不同主体类型:下游取值分支混乱。
  • Basic 走明文 HTTP:与 JWT 混用降低整体安全。

追问

  • 待确认:Ktor 3 多 provider 任一通过/全部通过的策略配置,以官方文档核对。
  • 如何区分调用来源?答:principal 中记录方案标识,审计按来源统计。

06.8.1.2-090 角色与权限校验放在哪一层?

一句话结论

粗粒度角色在授权拦截层按子树统一校验;细粒度数据权限在 Handler/服务层按主体与资源归属判定;认证只产出主体,授权不混入 provider 校验逻辑。

概念解释

角色是主体属性,权限是主体对资源的操作许可。角色校验可前置到路由子树,资源归属(本人订单、本租户数据)必须在访问具体资源时判定。两层都要可测试、可枚举回归。

原理流程

  1. 认证产出 principal 含角色。
  2. 拦截层按子树要求校验角色。
  3. Handler/服务层校验资源归属。
  4. 不通过返回 403。

代码或图示

if (principal.roles.contains("ADMIN")) {
    // 放行
} else {
    call.respond(HttpStatusCode.Forbidden)
}

常见误区

  • 角色判断散落在 Handler 各处:遗漏接口形成越权。
  • 只校验角色不校验数据归属:横向越权。

追问

  • 权限清单放哪里?答:主体携带或服务层查询,按权限模型设计;不要在代码里硬编码散点判断。
  • 待确认:Ktor 生态是否有授权注解/拦截扩展,以文档核对。

06.8.1.2-091 水平越权如何在 Handler 层防护?

一句话结论

访问资源时用主体标识与资源归属比对:只能访问本人/本租户数据;路径参数中的资源 id 不能直接信任,必须查出归属再判定;缺失归属记录按 404 或 403 统一处理。

概念解释

水平越权指同权限级别的用户互访数据。防御点在数据查询层:查询条件带主体/租户约束,而不是先取资源再判断。响应不区分「不存在」与「无权访问」时避免枚举,按安全约定选择状态码。

原理流程

  1. 从主体取当前用户/租户标识。
  2. 查询资源时带归属条件。
  3. 未查到按统一拒绝处理。
  4. 操作类接口同样校验归属后再执行。

代码或图示

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 防重放与泄露,内部服务防网络越权。按路由域隔离认证配置,主体类型区分调用方,日志与限流按域统计。

原理流程

  1. 定义调用方类别与信任边界。
  2. 各域装配对应 provider。
  3. 路由域引用各自认证策略。
  4. 授权与审计按调用方类型细分。

代码或图示

/web -> 会话 Cookie
/openapi -> Bearer 令牌 / 签名
/internal -> 服务凭据 / mTLS

常见误区

  • 一套令牌通吃所有调用方:权限与撤销粒度粗放。
  • 内部服务走公网开放接口:缺少网络层隔离。

追问

  • 待确认:内部服务 mTLS 在引擎/网关层的配置位置,按部署架构核对。
  • 调用方标识放哪里?答:principal 中记录类型与标识,审计按维度拆分。

06.8.1.2-093 匿名与已认证混合接口如何设计?

一句话结论

需要个性化时用可选认证:主体存在走登录逻辑,缺失走匿名逻辑;响应按主体区分缓存;强制公开内容不依赖主体;混合接口的错误处理对匿名与登录态分别明确。

概念解释

混合接口提升体验但增加分支:响应内容、缓存键、限流维度都要区分匿名与登录态。可选认证不能把非法令牌当匿名放行;前端按响应标识判断是否需要登录。

原理流程

  1. 接口声明可选认证。
  2. 读取可空主体。
  3. 分支生成对应响应。
  4. 缓存与限流按主体维度处理。

代码或图示

val principal = call.principal<UserPrincipal>()
val view = if (principal != null) personalized(principal) else anonymousView()

常见误区

  • 匿名分支也访问登录态数据:越权泄露。
  • 响应缓存不区分主体:登录内容被匿名命中。

追问

  • 待确认:可选认证 provider 配置方式,以官方文档核对。
  • 非法令牌在可选模式怎么处理?答:按策略拒绝或忽略,不能静默变匿名,安全上需明确约定。

06.8.1.2-094 主体过期如何实现无感刷新?

一句话结论

访问令牌短时效,前端 401 时用刷新令牌换新访问令牌;刷新接口独立认证,失败再引导登录;服务端不保存访问令牌状态,刷新令牌可吊销;多端刷新令牌分别管理。

概念解释

无感刷新发生在客户端请求链路:拦截 401 -> 调刷新 -> 重试原请求;刷新并发去重避免同时多次刷新。服务端关注刷新令牌校验、轮换与吊销,不感知前端重试细节。

原理流程

  1. 访问令牌过期,请求返回 401。
  2. 客户端携带刷新令牌换取新访问令牌。
  3. 刷新成功重试原请求;失败清除登录态。
  4. 刷新令牌轮换或失效后重新登录。

代码或图示

请求 401 -> 刷新令牌换发 -> 重试原请求
刷新失败 -> 清除会话 -> 重新登录

常见误区

  • 多个请求同时过期并发刷新:刷新令牌被多次轮换失效。
  • 刷新令牌长期有效不可吊销:泄露后无法收回。

追问

  • 待确认:项目前端刷新流程不在本节展开,服务端只提供签发与校验接口。
  • 刷新接口限流吗?答:按主体/设备维度限流,防刷新令牌爆破。

06.8.1.2-095 场景:开放 API 密钥签名认证如何接入?

一句话结论

为开放调用方分配 AccessKey 与 SecretKey,请求带标识与签名(方法、路径、参数、时间戳、随机串),服务端按相同规则重算签名比对;校验时间戳防重放,密钥可轮换与吊销。

概念解释

签名认证适合服务间开放 API:不传共享密钥,传签名摘要。服务端按 AccessKey 查密钥,拼接规范串用约定算法计算摘要,恒定时间比对。时间戳与 nonce 防重放,密钥按调用方隔离存放。

原理流程

  1. 调用方用 SecretKey 对规范请求串签名。
  2. 请求带 AccessKey、时间戳、nonce、签名。
  3. 服务端查密钥,重算签名并比对。
  4. 校验时间窗口与 nonce 后放行。

代码或图示

签名串:method + path + sortedParams + timestamp + nonce
服务端:同规则重算 -> 恒定时间比对 -> 时间戳/nonce 校验

常见误区

  • 密钥在日志或报文里出现:泄露即可伪造签名。
  • 不校验时间戳与 nonce:截获请求可重放。

追问

  • 待确认:签名算法与 nonce 存储方案按项目规范;Ktor 侧在前置拦截器实现校验。
  • 密钥轮换怎么做?答:双密钥过渡期,新签名用新密钥,旧密钥到期下线。

06.8.1.2-096 场景:管理后台 Session 与前端 Token 双模式如何共存?

一句话结论

管理后台浏览器走会话 Cookie,独立前端/移动 API 走令牌;两套认证 provider 分别挂在不同路由域,主体模型可统一;会话与令牌的过期、吊销、审计策略分别配置,凭据不跨模式复用。

概念解释

双模式常见于既有后台与新端侧接口并存。路由域隔离避免 Cookie 与令牌互相干扰;统一主体与权限模型让授权层一致。网络层与网关按域选择认证要求,避免公网暴露后台会话接口。

原理流程

  1. 划分后台路由与 API 路由。
  2. 分别装配 Session 与 Token provider。
  3. 统一 principal 结构与授权规则。
  4. 过期、吊销、审计按模式分别实现。

代码或图示

/admin/* -> Session Cookie(含 CSRF 防护)
/api/*  -> Bearer 令牌

常见误区

  • 两套模式挂在同一组路由:凭据处理逻辑混杂。
  • 后台会话接口暴露到开放网关:缺少网络隔离。

追问

  • 待确认:Session 插件与 JWT provider 共存的装配顺序,以官方文档核对。
  • 统一主体字段怎么设计?答:公共标识 + 模式/来源标识,权限字段一致。

06.8.1.2-097 插件装配顺序的安全检查清单有哪些?

一句话结论

上线前核对:认证在业务 Handler 之前、CORS 不放开凭据通配来源、安全头全局覆盖、序列化在响应包装之后、限流在认证前后按维度生效;用匿名与跨域用例回归全部受保护路径。

概念解释

顺序类问题多在测试环境难发现,靠清单化核对。安全相关插件层次:前置拦截(限流、来源、认证)-> 业务 -> 响应处理(包装、序列化、压缩、头)。每个插件的阶段与包裹对象在评审时明确。

原理流程

  1. 画出插件包裹层次图。
  2. 核对安全插件位于 Handler 前。
  3. 核对响应插件顺序不冲突。
  4. 跑匿名、跨域、超限、非法报文回归。

代码或图示

检查项:认证位置 / CORS 来源 / 安全头覆盖 / 限流维度 / 序列化顺序

常见误区

  • 只测正常登录路径:匿名与跨域未回归。
  • 新增接口忘记挂认证:路由块位置审查遗漏。

追问

  • 待确认:各插件默认阶段,以官方 pipeline 文档核对后画层次图。
  • 评审记录什么?答:插件顺序、职责边界、未覆盖的异常路径。

06.8.1.2-098 序列化有哪些安全注意点?

一句话结论

限制反序列化类型与深度,避免反序列化不可信多态类型;校验输入字段与大小;服务端 DTO 与领域实体分离;依赖序列化库打补丁,不解析未知危险格式;错误响应不泄露内部类型信息。

概念解释

反序列化漏洞来自构造恶意报文触发危险类型实例化或资源耗尽。kotlinx/Jackson 配置应关闭危险多态默认行为,限制嵌套深度与集合大小。输入只映射到白名单 DTO,不直接反序列化业务实体图。

原理流程

  1. DTO 字段白名单映射。
  2. 限制深度、集合与字符串大小。
  3. 关闭不安全多态/默认类型处理。
  4. 异常兜底为中性错误响应。

代码或图示

安全项:白名单 DTO / 深度限制 / 集合上限 / 关闭危险多态 / 库版本维护

常见误区

  • 直接把请求反序列化成领域实体:暴露内部结构与关联。
  • 不限制嵌套深度:恶意深嵌套打爆 CPU/内存。

追问

  • 待确认:所用序列化库的深度/大小限制配置项,以库安全文档核对。
  • 依赖漏洞怎么跟踪?答:定期扫描序列化库版本,按补丁升级。

06.8.1.2-099 生产认证配置常见漏配有哪些?

一句话结论

常见漏配:令牌不校验 issuer/audience、算法未固定、密钥进仓库、Cookie 缺安全属性、错误 401/403 混用、黑名单缺失、日志记录凭据、公开接口误挂或漏挂认证;上线前逐项清单核对。

概念解释

漏配多为默认配置未按生产基线收紧。核对维度:验签要素、密钥管理、Cookie 属性、状态码语义、撤销机制、日志脱敏、路由保护面。清单化在部署前检查,避免依赖代码评审记忆。

原理流程

  1. 按清单核对验签与密钥配置。
  2. 核对 Cookie 与响应头属性。
  3. 枚举路由确认认证挂载。
  4. 检查日志不含凭据明文。

代码或图示

漏配清单:声明校验 / 算法固定 / 密钥管理 / Cookie 属性 / 状态码 / 撤销 / 日志脱敏 / 路由覆盖

常见误区

  • 开发配置复制到生产:放宽项未收回。
  • 日志打印 Authorization 头:凭据随日志泄露。

追问

  • 待确认:各 provider 默认安全配置是否够生产基线,以官方安全文档核对。
  • 漏配怎么回归?答:匿名、过期、伪造、跨域用例枚举全部接口。

06.8.1.2-100 Ktor 认证与序列化生态相对传统框架能力如何对比?

一句话结论

Ktor 以插件 DSL 与协程管道组织认证/序列化,装配显式、轻量;传统框架依赖容器注解与自动装配,生态资料与企业集成更成熟;能力覆盖上两者都能完成常见认证与 JSON 场景,选型看团队与既有生态,本节不展开传统框架细节。

概念解释

对比维度:装配方式、插件成熟度、文档与招聘、与既有体系集成。Ktor 自定义管道灵活,但某些企业级认证组件生态不如传统框架丰富;落地前验证所需方案(JWT、Session、OAuth 等)在生态中的成熟度。

原理流程

  1. 列出所需认证与序列化能力。
  2. 核对 Ktor 生态组件成熟度。
  3. 对比团队经验与集成成本。
  4. 概念验证覆盖关键安全路径。

代码或图示

Ktor:显式插件 DSL、协程管道、轻依赖
传统框架:容器装配、注解生态、企业集成成熟度

常见误区

  • 假设 Ktor 生态与传统框架组件一一对应:小众方案可能需自研。
  • 只看框架性能不看认证组件成熟度:安全落地成本被低估。

追问

  • 待确认:Ktor 3 各认证/序列化组件当前维护状态,以官方与第三方仓库核对。
  • 传统框架细节见 06.2 分册,本节不重复展开。

参考来源

待整理清单

  • [ ] 核对 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 落地示例