OpenAPI：把接口输入、输出和错误说明白

接口文档要让调用方知道：能传什么、会收到什么、失败怎么区分。OpenAPI 把路径、方法、参数、正文、响应和安全方案写成工具可读取的格式，但不会替所有服务端自动检查。比如声明 quantity 最小为 1，仍需运行时代码正确读取、校验并拒绝不合法数量。

本篇使用 OpenAPI 3.1.1，其中用 Schema，也就是一份可由工具读取的数据规则，说明字段的类型和限制；它与 JSON Schema 2020-12 体系相关。先分清四种情况：没传字段、传了 null、传了空字符串、传了数字 0。

required 只规定字段必须出现；能否为 null，还要看类型规则，不能照搬旧版的 nullable 写法。路径参数有额外要求：in: path 的参数必须声明 required: true。

契约不只包含成功 DTO。调用方还需要知道参数错误、未认证、权限不足、对象不可见、业务冲突和依赖失败如何表示。响应应包含媒体类型、字段类型和稳定错误结构，避免只写一个 description 就认为接口已定义完整。内部数据库列与外部 DTO 各有演进周期，不应自动把所有数据库字段暴露成响应。

先选定一个具体操作，列出路径、HTTP 方法与输入来源：path、query、header 或请求体。再定义必填字段和约束。创建订单示例要求 skuId 为正的 int64 范围整数、quantity 为一到一百的整数，note 可缺失或为 null，若是字符串则最多二十个码点，额外属性拒绝。这样的精确边界才能指导实现和测试。

相应 Schema 的关键声明是 type: object、required: [skuId, quantity] 和 additionalProperties: false；属性 skuId、quantity 使用 type: integer 及 minimum、maximum，note 使用 type: [string, 'null'] 与 maxLength: 20。

完整 OpenAPI 文档还需 openapi、info、paths、requestBody 和 responses 等上下文，本段只是用于解释约束的局部说明。

JSON Schema 的整数关注数学值，而不只看文本是否出现小数点，因此 1.0 可以是整数，1.5 不可以。Java 绑定层若直接用 longValue 截断，会把后一种错误输入变成看似合法的一。应明确解析器数字策略，使用精确转换或校验；format: int64 也不应被假定在每个工具中都自动执行同样的范围检查。

请求通过结构校验后，还需要业务规则和对象授权。例如订单编号是合法正数，并不代表当前用户可以读取该订单。OpenAPI security scheme 描述认证方式，实际凭据验证由服务执行，对象所有权还需结合业务数据检查。返回 404 隐藏不可见对象或返回 403 的选择应按产品安全策略一致实现。

契约验证应双向进行：非法请求被正确拒绝，合法响应也符合声明。针对缺失、null、边界和他人对象等用例检查真实状态码与结构，避免文档和实现各自通过却互不一致。新增响应字段常对宽容客户端兼容，但严格拒绝额外字段的客户端可能失败，因此不能脱离消费者行为宣称新增字段一定兼容。

本机 BigDecimal.toBigIntegerExact 使用不允许舍入的方式将 scale 调整为零，再返回整数表示。非零小数部分会导致 ArithmeticException，而诸如 1.0 这样的值可以精确转换。这与普通 longValue 可能丢弃小数部分的行为不同，正好对应接口整数绑定需要明确拒绝非整数的边界。

教学模型在精确转换之前检查正数和 long 上界，避免把超出业务范围的值继续当作候选编号。它是原创的 Java 数值校验片段，没有实现 JSON 解析器，也不是 OpenAPI 或 JSON Schema 引擎。输入已经被解析为 BigDecimal 的前提必须由接入层兑现，不能对任意 Number 随意强转。

限制最终数字不能超过 long，并不限制解析它要花多少资源。数字文本长度、指数范围和整个请求大小，应在解析阶段就限制，否则可能还没到业务校验就分配大量内存。精确转换保证数字没被悄悄截断，但不能独自处理所有超大输入问题。

完整算法用有限的固定字段展示存在性、类型、范围和额外字段检查，不声称覆盖 allOf、引用、条件 Schema、递归对象或所有格式。真实项目采用成熟校验器时，也应核对启用的方言与选项，并以相同边界案例验证绑定后的实际行为。

输入已解析的 Map：数字统一为 BigDecimal，字符串为 String，null 保留。按固定字段顺序返回错误路径与代码，未知字段按名字排序；不解析 JSON，不执行授权或下单。

首先使用 containsKey 判断必填属性，而不是只调用 get，因为 get 返回 null 可能代表缺失，也可能是明确传入 null。数字类型只接受本题约定的 BigDecimal，字符串形式的 '2' 不被自动转换，避免文档说数字而运行时却接受多个含糊表示。

对数字使用 stripTrailingZeros 后的 scale 判断是否为数学整数，再检查上下界。这样 1.0 与 1 都合法，1.5 被拒绝。校验不通过就记录该字段第一个明确错误，返回顺序固定，便于客户端测试和排障；是否聚合全部错误是接口契约的一部分。

note 独立处理可缺失与可空语义，非空时要求字符串并按码点数限制长度。未知属性统一收集并排序，防止客户端误拼字段名却被服务静默忽略。算法不生成业务对象，也不证明 skuId 存在或用户有权限，这些步骤在结构通过之后另行执行。

固定已知字段只检查有限次，未知字段排序提供稳定输出；码点计数和 BigDecimal 操作不能忽略输入长度。

接口文档应和实现一起评审，特别是错误码、必填字段、分页，以及时间金额写法。自动生成文档能减少手写不同步，但只看 DTO 仍可能漏掉对象权限、状态冲突或多个字段之间的规则。这些行为要用说明与请求测试表达，不能按注解多少判断接口是否完成。

拒绝未知字段能发现拼写错误，却要求客户端和服务端更紧密地协调更新；允许未知字段可能方便演进，也可能隐藏传错参数。请求与响应可以用不同策略。判断是否兼容，要看真实客户端怎样解析枚举、数字和 null，不能只比较是否多了一个字段。

响应错误格式应提供稳定机器码、合适的字段路径和可公开说明，内部堆栈留在服务端关联日志。认证与对象授权应在实际执行路径落实，并用不同身份访问同一资源验证。结构校验失败、权限失败和依赖故障应分别观察，避免全部转换为一个成功状态加错误文本，让调用方无法可靠处理。

解析、验证和执行业务各自需要资源上限。限制请求体、字段长度和嵌套深度，可以让不合法输入尽早停止；错误聚合也应有数量上限。这里的小型校验器用于推导规则，生产系统应选择支持所需方言的成熟组件，并保留针对实际绑定层的回归测试。