1. 参数校验放在网关层的真实理由不只为了省事我接手网关改造项目的时候团队里吵得最凶的就是一句话参数校验到底该放哪一层。业务服务说网关校验是重复劳动网关团队说业务服务校验不可信。吵到最后大家才发现真正的分歧不在于要不要校验而在于校验到底在保护谁。先说一个我实测过的场景。某个内部系统对外开放了POST /api/order/create业务团队只对必填字段做了空判断没有限制字段长度和类型。结果运维日志里出现了一条请求remark字段塞了 64KB 的 Base64 字符串直接把业务服务的内存占满节点频繁 OOM。事后排查发现这不是恶意攻击就是一个客户端 bug——用户上传了一份 JSON 文件前端没截断就整包提交了。如果网关在入口处就做了字段长度校验这条请求根本到不了业务服务。所以我的结论很直接参数校验放网关不是为了替代业务的校验而是为了给整条链路设一道公共的入口闸门。业务层的校验依然要做但那是为了保证业务逻辑正确网关层的校验则是为了抵御畸形数据、超限数据、恶意探测。两者的目标根本不同。1.1 没有校验的网关会发生什么我把踩过的坑列成了一张表每次给新同学讲网关设计都会先丢这张表问题类型表现根因内存打爆大字段直接进 JVM/Node 堆没有长度上限路由绕过路径参数带..或编码斜杠没有规范化校验注入探测字段内容触发 SQL/NoSQL 注入没有字符集白名单协议混乱Content-Type与实际 body 不符没有协议层校验参数篡改客户端改价、改折扣没有签名/指纹校验这里面最隐蔽的是路由绕过。我之前见过一个网关配置路径匹配用的正则允许%2e%2e%2f这类的 URL 编码结果攻击者用/%2e%2e/admin绕过了前端鉴权路由直接访问到内部管理界面。后来我们在网关里加了路径规范化校验先解码再判断是否包含..才算堵住这个洞。1.2 网关层校验与业务层校验的分工很多人问如果网关已经校验了业务服务是不是可以省掉校验答案是绝对不行。网关校验是粗粒度防线业务校验是细粒度规则。举例来说网关能校验userId是不是数字但校验不了这个用户是否属于当前订单所属商户后者必须依赖数据库和业务状态。所以我的分工原则是三条网关负责语法校验格式对不对、协议校验是不是合法 HTTP、基本约束长度、类型、范围、安全校验签名、时间窗、频率。业务负责语义校验业务规则是否允许、权限校验数据归属权、状态机校验状态流转是否合法。重复校验怎么处理性能敏感字段比如查询参数可以只保留网关校验写操作相关的重要字段业务侧也建议保留兜底防止后续有其他入口绕过网关。这个分工说出来很简单但真正落地难在网关校验规则到底归谁维护。我见过网关定了一套长度规则业务服务也定了一套两边不一致结果线上出现同一字段一边收一边拒的诡异问题。解决办法是把通用的校验规则沉淀成一份共享的 Schema 描述文件网关和业务服务都从这份文件生成校验器从源头消灭不一致。2. 我常用的四种参数校验策略前面说的是为什么这一段聊怎么做。我这些年大大小小维护过几套网关踩了无数坑之后收敛出了四类策略按层级从低到高分别是协议层校验、基础参数校验、跨字段校验、契约校验。下面一个个拆开讲。2.1 协议层校验先别急着看参数先看请求本身有相当大比例的畸形流量根本轮不到参数校验出场在协议层就被拦截了。协议层校验的核心是请求行、请求头、Content-Type 这三个东西是不是自洽。我自己在 Nginx 里做过一个最简单的协议检查场景只允许 JSON 格式的 POST 请求。很多人以为看Content-Type等于application/json就够了实际上不够。常见坑有Content-Type: application/json; charsetutf-8带了 charset字符串精确匹配会漏。Content-Type大小写混写Application/JSON。客户端声明了 JSON但 body 实际是空字符串。Multipart 上传时Content-Type 带了 boundary直接按 JSON 解析会导致整个请求 400。我推荐的做法是Content-Type 用前缀匹配 标准化 parser先解析后判断而不是先判断后解析。完整步骤是读取Content-Typeheader。按;切分取第一个 segment。转小写、去空白。再与application/json做比对。在 Lua 或 Python 里这是几行代码的事但收益非常明显——协议层挡掉的垃圾请求大概能占总拦截量的两成。再把Content-Length与 body 实际长度做匹配还能顺带防住分块传输里常见的请求走私变体。2.2 基础参数校验类型、边界、枚举协议层校验过了就要看参数本身。我把基础参数校验拆成四类类型校验该是数字的不能是字符串该是布尔值的不能是0/1/true/false混着来。这里最容易犯的错是用宽松模式——比如把字符串123自动强转成数字 123。我强烈建议网关层别做隐式转型原因后面讲精度问题时展开。严格模式下123就直接拒绝客户端必须自己传正确类型。边界校验长度上限、数值范围、数组最大元素个数。这里的重点不是设置一个上限而是区分上线和业务上限。比如remark字段业务上允许 500 字但网关可以限制 1024 字节因为 500 字可能是用户视角字节数才是服务器实际占用。这个差异不处理就会出现用户怎么都提交不了一个 300 个中文备注的问题——因为len()按字符算但存储按 bytes 算编码差异导致误伤。枚举校验状态字段、类型字段、语言字段必须限定在合法的取值集合里。我见过一例订单状态传了个SUCCESSED多了个 E结果下游状态机怎么都匹配不上订单卡死。如果在网关层加上枚举校验这笔请求会在第一秒就被打回而不是一路传到底层数据库。格式校验手机号、邮箱、身份证号这类结构型字段。这里有个细节网关层尽量用正则匹配而不要调用重量级 SDK 做号码归属地校验之类的事性能和职责都不合适。正则要写得足够保守宁可漏放也别误杀因为误杀造成的用户投诉远比拦截恶意请求更令你头疼。2.3 跨字段校验时间戳、幂等键、Sign 指纹基础参数校验管的是单个字段但相当一部分安全问题藏在字段之间的关系里。这类校验我统一归类为跨字段校验也是网关层最容易被人忽略的盲区。时间戳窗口校验接口字段里带ts时间戳用来防重放攻击。网关拿到ts后先算abs(now - ts)超过某个窗口比如 5 分钟直接拒绝。这里要注意客户端和服务端的时间可能不一致窗口别设太小否则你的正常用户体验会崩。我见过设成 30 秒的结果一堆用户请求全部被判为过期。合理做法是 5 分钟窗口 允许 1 分钟时钟偏差双条件取一个大的宽松值。幂等键校验写接口通常要求客户端生成一个Idempotency-Key。网关层的职责不是校验这个 key 有没有业务意义而是校验它的格式和唯一性基础——长度、字符集、是否为空。实际实现时key 会进 Redis 做去重但网关必须先拒绝非法 key比如超过 128 字符的、带非 ASCII 字符的避免 key 成为 Redis 的滥用入口。Sign 指纹校验这个是最复杂的跨字段校验。网关拿到请求后要按约定把所有参与签名字段做字典序排列拼成一个字符串用共享密钥做 HMAC再与客户端传来的sign字段比对。这里面不仅有校验逻辑还有签名覆盖哪些字段的规则。我的经验是协议设计时就应该规定签名必须覆盖请求内容主体否则攻击者改了 body 里未被签名的字段签名校验形同虚设。2.4 契约校验OpenAPI Schema 驱动到了微服务多团队协作的规模手写网关校验规则已经不够了因为每新增一个接口都要改一遍网关配置成本太高。我最后落地方案是把校验规则直接写进 OpenAPI就是原来的 SwaggerSchema网关在运行时引用这份 Schema 自动完成校验。具体流程是各业务团队在开发接口时维护一份 OpenAPI 文档字段的type、minLength、maxLength、enum、pattern都定义清楚。网关启动时拉取所有服务的 OpenAPI 文件编译成内部的 JSON Schema。请求进来时网关根据method path定位到对应的 operation用请求 body 去匹配对应的 JSON Schema。匹配失败的请求直接返回 422附带完整的错误路径和原因。这套做法的核心好处是校验规则和接口定义天然同源不会出现文档和线上线下两套规则。缺点也明显JSON Schema 校验性能开销比手写校验大。我实测过简单对象校验大概会增加 1ms 到 3msP99但复杂嵌套对象不加节制地写allOf/oneOf时会飙升到十几 ms所以性能敏感接口要控制 Schema 的复杂度。3. 在 OpenResty/Nginx Kong 里落地参数校验的实操记录聊完策略说点真实落地的过程。我现在这套网关是基于 OpenResty 自研的身边也有不少在用 Kong、APISIX 的朋友。手动全代码实现最痛苦的地方不是校验逻辑本身而是校验规则怎么写、怎么加载、怎么热更新。下面是我踩过一遍之后沉淀出来的完整方案。3.1 基于 lua-resty-validator 的实现方案我里里外外对比过好几个 Lua 校验库最后选了lua-resty-validator原因是它直接用 JSON Schema 风格定义规则能和我前面说的契约校验对得上。先给一段我当时写的核心代码结构local validator require(resty.validator) local schema { type object, properties { user_id { type integer, minimum 1 }, amount { type number, exclusiveMinimum 0 }, remark { type string, maxLength 512 }, status { type string, enum { pending, paid, cancelled } } }, required { user_id, amount }, additionalProperties false } local function validate_params(params) local v, err validator.new(schema) if not v then return nil, invalid schema: .. err end local ok, err v:validate(params) if not ok then return nil, err end return true end这段代码的要点有几个additionalProperties false一定要开否则客户端传一个你没定义过的字段校验器不会报错。很多安全漏洞的风险点就在这里攻击者塞一个可疑字段进来网关不拦截到了业务服务里被当成某个内部配置项去读就出大事了。required里声明必填字段但注意区分字段不存在和字段值为 null很多校验库会把两者都判为失败实际你的业务可能允许显式传 null 来清空某个字段。这个坑我在第 4 节细说。exclusiveMinimum在 JSON Schema 的 draft-04 和 draft-06 里写法不同老版本库和新版本库兼容性会坑你所以选定库之后要锁版本不能随手升级。3.2 Schema 配置解耦与热更新代码写完之后最烦人的是规则变更。一开始我把 schema 写死在 Lua 文件里每次改个长度上限都要重新打包网关。后来我把 schema 抽出来放到独立的 JSON/YAML 配置文件里由网关在请求间隙重新加载。配置长这样paths: /api/v1/order/create: post: requestBody: content: application/json: schema: type: object properties: user_id: { type: integer, minimum: 1 } amount: { type: number, exclusiveMinimum: 0 } required: [user_id, amount]然后 Lua 端做一个带缓存的加载器local cache ngx.shared.schema_cache local schema_json cache:get(schema_ .. route_key) if not schema_json then local f io.open(/etc/gw/schemas/ .. route_key .. .yaml, r) schema_json f:read(*a) f:close() cache:set(schema_ .. route_key, schema_json, 60) end这里的核心是 60 秒缓存的 TTL。我实际用下来发现太短会导致每 60 秒有一两个请求需要重新加载文件P99 轻微抖动太长又没法及时生效。折中下来 60 秒是个合理的值紧急变更时可以手动清一下共享缓存立即生效。3.3 性能开销实测与超时防护讲一下我最关心的性能数据。我在压测环境跑过 1000 QPS 的纯转发请求对比加校验和不加校验场景P99 延迟内存增量纯转发不校验2.8 ms0基础参数校验4.2 ms~0.3 MB基础 跨字段签名校验6.7 ms~0.6 MB基础 Schema 校验简单对象7.5 ms~1.2 MB从这个表能看出校验的开销在大多数业务场景下是可接受的。但有一个坏情况必须防验证器陷入复杂正则的回溯。某些 Schema 里写了个过于宽泛的嵌套正则比如(a)$恶意构造一个超长字符串正则引擎可能跑几百毫秒甚至超时直接拖死 worker 进程。我最终的解决思路有两条所有正则校验统一加ngx.re.match的o编译选项 ctx超时控制Lua 里用ngx.re自带的正则编译缓存。在网关入口做一次请求 body 大小上限拦截超过比如 256KB 直接 413从源头避免超大字符串进入正则引擎。4. 参数校验最容易踩的五个坑校验逻辑看起来简单真正上线后全是看起来正常、细想不对劲的边界问题。我把自己踩过和看过别人踩的坑整理成五个你读完至少能避开九成。4.1 字符串截断与 Unicode 边界字符串长度校验最容易翻车的就是 Unicode。很多校验器按字符数#str计算但 HTTP body 里的字节长度和字符长度是两回事。一个中文字符在 UTF-8 下占 3 字节你限了 100 个字符web 防火墙可能看的是 300 字节两边口径不一致正常请求被误杀。还有一种情况是 emoji 和组合字符像这种一个用户可感知的字符Unicode 码点可能有好几个。如果网关按码点切分长度就会把这个家庭组合 emoji 当成 7 个字符。业务要求的长度不超过 20 个字在用户感知层面错了。我的解决办法对用户可见文本字段校验上限用字节数并留一定余量比如用户输入 100 字符网关宽容到 400 字节同时对截断操作禁用宁可拒绝也不截断避免多字节字符被切一半导致后续存储乱码。4.2 数字精度丢失与整型溢出JSON 里的数字类型是number但在不同语言里实际落地可能是double、int64或者BigDecimal。网关层用 Lua 时Lua 的 number 是双精度浮点一旦你的字段是id这种 64 位大整数比如1321736142356488192在 Lua 里会被转成1321736142356488200精度丢了校验通过但业务侧拿到的是错误 ID。这类问题是最难排查的因为你看到的日志都是数值不对齐时肉眼很难发现最后几位差异。我的经验是凡是 ID 类、金额类字段网关一律按字符串接收和校验而不是数字类型。在校验 Schema 里把类型定义为string然后用pattern或者长度限制来约束格式这样既能做基础校验又不丢精度。金额类字段还要额外注意浮点运算陷阱网关里不要对金额做任何加减乘除只做格式检查真正计算交给业务侧用BigDecimal。4.3 null、缺省与默认值的区别JSON 里有三种表达完全不同的语义字段不存在、字段值为null、字段值为null字符串。很多校验器默认把null当成不合法但实际业务里用户可能故意传null来清空某个字段比如把email置空。如果你在网关层一刀切拒绝null很多正常的清空操作会失败。我的做法是在 Schema 里显式区分nullable和required。required表示字段必须出现在 JSON 里但允许值为null如果想禁止null再加一个not: { type: null }来约束。实测下来最稳的是在网关侧定义三层状态missing字段不存在由required控制。explicit null字段存在但值为 null由nullable控制。empty string空字符串应视为有效但可能是无意义值单独用minLength: 1控制。这套设计的前提是网关团队能把自己的需求说清楚否则校验器会变成一团浆糊什么规则都想加最后误伤一片。4.4 错误信息泄露内部逻辑校验失败返回的报错信息很多人不在意直接随手返回一个带有内部校验逻辑的 msg。比如{ error: field user_id must match pattern \^[0-9]$\ }这种信息对攻击者来说就是免费的情报他知道你用的是什么正则、什么样的值会被放行然后可以针对性地构造绕过 payload。另一个更严重的场景是返回内部字段名和校验库版本攻击者可以据此探测你的技术栈甚至找到已知漏洞。我的原则是给客户端的错误信息永远只有三个层级第一层INVALID_PARAM第二层MISSING_REQUIRED_FIELD第三层VALIDATION_FAILED除非是调试模式否则不返回具体字段名和校验规则细节。内部排查时把完整错误信息记到网关日志里用 traceId 关联这不影响调试效率。4.5 校验顺序影响防攻击效果校验流程也不是随便排列的。错误的顺序会导致防护效果剧烈恶化。我建议的固定顺序是TLS 终止与协议解析Content-Type 与 Content-Length 校验链路级频率限制与黑白名单路径规范化与路由匹配通用 Header 校验如 Host、Authorization 格式Body 大小上限检测签名/时间戳校验字段级 Schema 校验业务幂等键查重为什么顺序重要最典型的是如果你先做字段级校验再做签名校验攻击者不需要签名只要畸形字段就能触发大量校验逻辑等于把你的网关变成了正则引擎的 DoS 放大器。更合理的是廉价校验先做昂贵校验后做签名校验通常涉及 HMAC 计算开销不小但要防止未签名流量直接打到底层字段校验所以我的顺序里把签名放在字段级之前并且对没有签名的请求直接拒绝。5. 不同规模团队的选型思路参数校验不是技术问题更是组织问题。什么样的团队规模、什么样的网关形态直接决定你该选哪种方案。我按三种典型形态说一遍方便你对号入座。5.1 小型单体别搞微网关用中间件就够如果是单体应用加上一个 Nginx 做反向代理这个阶段做参数校验最划算的方式是直接写中间件而不是硬塞一个 API 网关。我见过团队只有两三个服务却去硬上 Kong结果维护成本翻了好几倍得不偿失。单体场景下的最佳路径是在 Web 框架里加一个全局中间件统一拦截请求。中间件里用框架自带的 validator 做基础校验。Nginx 层只做协议层拦截Content-Type、body 大小、连接数限制。这个方式的好处是逻辑自己掌控报错格式统一改动一行代码全站生效。坏处也很明显如果后续服务拆成多个微服务校验逻辑必须往外搬所以单体阶段也别把校验写死在 Controller 里尽量抽成独立的校验模块为将来迁移做准备。5.2 中型微服务Kong / APISIX 插件化到了几十个服务单纯用框架中间件就失控了因为每个服务都要自己实现一遍同样的校验规则不一致的问题又回来了。这个阶段适合用开源的 API 网关Kong 和 APISIX 都可以核心优势是插件化校验。以 APISIX 为例我常用的是request-validation插件可以直接配置一套 JSON Schema 规则plugins: - name: request-validation enable: true config: header_schema: {} body_schema: type: object properties: user_id: { type: integer, minimum: 1 } remark: { type: string, maxLength: 512 } required: [user_id]这里要提醒插件的body_schema规则最好由契约驱动也就是从 OpenAPI 里自动生成不要手工维护。手工维护几个服务后就开始失控。5.3 大型平台服务网格与中央配置当服务数量超过一百网关本身会演变成一个平台。这个时候的参数校验不再是一个插件能搞定的事需要在服务网格如 Istio的 Envoy Filter 里写自定义 Filter或者采用中心化的规则配置中心。我的建议是不管底层用什么规则定义一定要集中到一个能审计、能灰度发布的地方。推荐的做法是用 JSON Schema 文件作为唯一规则真源。网关启动时拉取运行时监听变更以秒级方式热更新规则。对校验失败的数据打点上报到可观测平台方便做报警和规则调优。每个接口的校验规则要有责任人变更走 review 流程避免乱改误伤线上。6. 校验收尾再聊两个长期有用的习惯如果你只是一次性需求看完前面几节就够了。但如果你像我一样要长期维护一整套网关下面这两个习惯能帮你少掉很多头发。第一个习惯是把参数校验的拦截率当成一个核心指标来监控。不要只看接口 200 比例要看网关 422/400 比例。这个比例突然飙升通常意味着有客户端升级出 bug或者有人开始批量扫接口。我一般设两个阈值3 分钟内的 422 率超过 5% 就报警超过 10% 直接暂停对应接口的写操作。这样鲁莽的 bug 版本不会在一瞬间污染整条数据链路。第二个习惯是每个接口都要有校验规则灰度开关。新接口上线时校验可以先以 warn-only 模式运行只记录日志但不断请求等观察两天确认没有误杀再切换为 enforce。这个习惯救过我很多次尤其是团队从其它语言迁移过来时对长度限制、枚举值边界理解不一致直接 enforce 一定会翻车。至于最终要不要把所有校验都搬进网关我的看法是不要为了架构面子而过度设计。网关参数校验的边界应该是那些跨服务通用、性能可承受、语法类检查的规则真正的业务状态校验留在下游。你在设计阶段先问自己一个问题这个规则换成业务服务实现会不会有跨服务的不一致风险如果不会那下游校验就够了。把有限的网关算力花在真正值得拦截的攻击和畸形流量上性价比才是最高的。
