API 入参校验是接口安全的第一道关口:同一份参数在前端被拦下、在入口层被放过、在业务代码里又被拼进 SQL 或命令,越权与注入往往就诞生在这种口径不一致的缝隙里。本文用 JSON Schema 把参数契约写成机器可读的描述,在应用入口做运行时校验,再用 OpenAPI 契约测试把「文档里写的」和「代码里做的」对齐,所有配置与命令均可直接复制执行。
适用场景
以下情况说明接口缺少可执行的参数契约,只靠代码里的零散判断无法收敛风险:
- 接口参数结构复杂,嵌套对象、数组、枚举混在一起,手写 if 判断越写越乱,漏一个字段就留下越权入口;
- 同一个字段在注册接口限制 20 字符、在资料修改接口不限制,攻击者用宽松接口写入超长内容,再在严格接口触发异常;
- 前端做了类型校验,后端直接信任
Content-Type: application/json的请求体,构造请求即可提交任意字段; - 接口文档由人工维护,字段增删后文档滞后,测试与前端按旧文档调用,异常参数直接打到数据库层;
- 需要为 WAF 之外再补一层「结构合法性」判断,让明显畸形的请求在进入业务逻辑前就被拒绝。
前置条件
- Node.js 不低于 18.x,使用
ajv8.x 时须显式引入ajv/dist/2020才能支持 draft 2020-12; - Python 不低于 3.10,
jsonschema建议 4.21 以上,schemathesis建议 3.29 以上; - 接口已有 OpenAPI 3.x 描述文件,或能从框架自动导出(FastAPI 自带
/openapi.json); - 准备一份可回放的测试环境,契约测试会发送大量随机请求,不要直接打生产库;
- 约定统一错误码:参数类错误固定返回 400 与
INVALID_PARAM,便于日志聚合与告警。
原理说明
JSON Schema 是一份描述「合法 JSON 长什么样」的声明式文档:type 约束类型,required 约束必填,additionalProperties: false 拒绝未声明字段,pattern 与 maxLength 限制字符集与长度,enum 把取值收敛到白名单。校验器读取这份文档生成判断逻辑,参数通过才进入业务层。它的价值不在「比 if 更强」,而在把校验规则从代码里抽出来变成可版本管理、可跨语言复用、可被测试直接消费的资产。
校验器有几个参数直接决定安全性。coerceTypes 若开启,字符串 "1" 会被自动转成数字 1,看起来方便,实际会让类型混淆类攻击更容易穿过;removeAdditional 若开启,未声明字段被静默删除而不是报错,攻击者提交的 role=admin 会被悄悄丢掉,看似安全但掩盖了攻击意图。strict 模式则要求 Schema 里不出现无法识别的关键字,防止把 require 误写成 required 这类低级错误带进生产。建议三者取值为 false / false / true。
运行时校验只解决「进来的参数是否合契约」,剩下的一半问题是「代码是否真的按契约实现」。契约测试的做法是:从 OpenAPI 描述生成请求,按字段类型、边界值、必填项构造用例,再把响应状态码与响应体结构与文档声明比对。凡是文档说必填、实现却不校验的字段,或者文档说返回 400、实际返回 500 的路径,都会在测试里暴露。两者组合,才构成从声明到实现的闭环。
操作步骤
第一步:安装校验依赖
两端各装一套,Schema 文件共用同一份,避免各写一套规则产生偏差:
# Node.js 侧:ajv 8 + 常用格式校验
npm install ajv ajv-formats
# Python 侧:Schema 校验 + OpenAPI 文档校验 + 契约测试
pip install "jsonschema>=4.21" openapi-spec-validator "schemathesis>=3.29"
# 确认版本,ajv 8 以下不支持 draft 2020-12
node -e "console.log(require('ajv/package.json').version)"
python -c "import jsonschema; print(jsonschema.__version__)"
版本不匹配是最常见的第一道坎。ajv 6.x 只支持 draft-07,遇到 $schema 声明 2020-12 的文档会直接抛 no schema with key or ref,此时不要改 Schema 迁就库,应当升级库。
第二步:编写参数契约
把 Schema 放在独立目录,文件名与接口路径对应,便于后续按接口审查。下面的例子描述一个创建用户的请求体,重点在三个约束:additionalProperties 关闭多余字段、role 用枚举封死、字符串统一加长度上限。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://api.example.com/schemas/user-create.json",
"title": "UserCreate",
"type": "object",
"additionalProperties": false,
"required": ["username", "email", "role"],
"properties": {
"username": {
"type": "string",
"minLength": 3,
"maxLength": 20,
"pattern": "^[a-zA-Z0-9_]+$"
},
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"role": {
"type": "string",
"enum": ["user", "editor"]
},
"age": {
"type": "integer",
"minimum": 18,
"maximum": 120
},
"profile": {
"type": "object",
"additionalProperties": false,
"properties": {
"nickname": { "type": "string", "maxLength": 32 }
}
}
}
}
几个容易写错的点:maxLength 与 pattern 是同时生效的,缺一个都可能放过超长或含特殊字符的输入;format: email 在 ajv 里必须配合 ajv-formats 才实际校验,否则只是注释;additionalProperties: false 只作用于当前层级,嵌套对象要单独声明,否则 profile 里塞任意字段仍能通过。
第三步:在入口层接入运行时校验
校验必须放在业务逻辑之前,且失败即以 400 终止,不能「校验失败但继续执行」。下面是 Express 中间件的完整实现:
// validate.js
const Ajv2020 = require("ajv/dist/2020");
const addFormats = require("ajv-formats");
const userCreateSchema = require("./schemas/user-create.json");
const ajv = new Ajv2020({
allErrors: true, // 一次性返回全部错误,便于前端定位
strict: true, // 拒绝未识别的关键字,防止拼写错误失效
coerceTypes: false, // 关闭隐式类型转换,避免 "1" 变 1
removeAdditional: false,// 多余字段报错而不是静默删除
useDefaults: false,
});
addFormats(ajv);
const validateUserCreate = ajv.compile(userCreateSchema);
function validateBody(req, res, next) {
if (!validateUserCreate(req.body)) {
const errors = (validateUserCreate.errors || []).map((e) => ({
path: e.instancePath || "/",
rule: e.keyword,
message: e.message,
}));
return res.status(400).json({ code: "INVALID_PARAM", errors });
}
next();
}
module.exports = { validateBody };
// app.js
const express = require("express");
const { validateBody } = require("./validate");
const app = express();
app.use(express.json({ limit: "64kb" }));
app.post("/api/users", validateBody, (req, res) => {
res.status(201).json({ id: 1001, username: req.body.username });
});
limit: 64kb 这一行不能省。JSON 解析发生在校验之前,若请求体上限设成默认的 100MB,攻击者用一个超大 JSON 就能在校验器执行前把内存吃满,这属于典型的「校验前的资源消耗」。Python 侧同理,中间件要在读取 body 之后、路由处理之前完成判断:
# middleware.py
import json
from pathlib import Path
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from jsonschema import Draft202012Validator, FormatChecker
SCHEMA_DIR = Path(__file__).parent / "schemas"
_validators = {}
def get_validator(name: str) -> Draft202012Validator:
if name not in _validators:
schema = json.loads((SCHEMA_DIR / f"{name}.json").read_text("utf-8"))
_validators[name] = Draft202012Validator(
schema, format_checker=FormatChecker()
)
return _validators[name]
app = FastAPI()
ROUTES = {("/api/users", "POST"): "user-create"}
@app.middleware("http")
async def schema_guard(request: Request, call_next):
key = (request.url.path, request.method)
if key in ROUTES:
raw = await request.body()
if len(raw) > 64 * 1024:
return JSONResponse({"code": "PAYLOAD_TOO_LARGE"}, status_code=413)
try:
data = json.loads(raw or b"{}")
except json.JSONDecodeError:
return JSONResponse({"code": "INVALID_JSON"}, status_code=400)
validator = get_validator(ROUTES[key])
errors = sorted(validator.iter_errors(data), key=lambda e: list(e.path))
if errors:
detail = [
{
"path": "/" + "/".join(str(p) for p in e.path),
"rule": e.validator,
"message": e.message,
}
for e in errors
]
return JSONResponse(
{"code": "INVALID_PARAM", "errors": detail}, status_code=400
)
return await call_next(request)
注意 iter_errors 会返回全部错误,而 validate 只告诉你是否通过。对外只暴露 rule 与 path,不要回显 Schema 全文,否则等于把内部数据结构送给了攻击者。
第四步:用契约测试比对文档与实现
运行时校验保证请求合法,契约测试保证实现与文档一致。先导出 OpenAPI 描述,校验文档本身合法,再让工具按契约生成请求:
# 1. 导出并校验 OpenAPI 描述文件
curl -s http://127.0.0.1:8000/openapi.json -o openapi.json
openapi-spec-validator openapi.json
# 2. 全量契约测试:按字段类型与边界值生成用例
schemathesis run openapi.json \
--base-url http://127.0.0.1:8000 \
--checks all \
--hypothesis-max-examples 50 \
--request-timeout 5000
# 3. 只测目标接口,失败即退出(适合放进 CI)
schemathesis run openapi.json \
--base-url http://127.0.0.1:8000 \
--endpoint /api/users --method POST \
--checks status_code_conformance,response_schema_conformance \
--exitfirst
status_code_conformance 检查实际返回码是否落在文档声明的集合内,response_schema_conformance 检查响应体结构是否符合 Schema。这两个检查项最容易暴露「文档写 400、代码抛 500」的问题。--exitfirst 让首个失败立即中断,避免 CI 里刷出几百行重复报告。把这三条命令写进流水线,即可在合并前拦住契约漂移:
# .github/workflows/api-contract.yml
name: api-contract
on: [pull_request]
jobs:
contract:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install openapi-spec-validator "schemathesis>=3.29"
- run: openapi-spec-validator openapi.json
- run: docker compose up -d api
- run: |
for i in $(seq 1 30); do
curl -sf http://127.0.0.1:8000/health && break
sleep 2
done
- run: |
schemathesis run openapi.json \
--base-url http://127.0.0.1:8000 \
--checks all --exitfirst
配置验证
校验层上线前,用下面六个请求逐条确认行为符合预期,全部通过再放流量:
BASE=http://127.0.0.1:8000/api/users
H='Content-Type: application/json'
# 1. 合法请求,期望 201
curl -s -o /dev/null -w "%{http_code}\n" -X POST $BASE -H "$H" \
-d '{"username":"alice","email":"alice@example.com","role":"user"}'
# 2. 缺少必填字段,期望 400
curl -s -X POST $BASE -H "$H" -d '{"username":"bob"}' | head -c 300
# 3. 类型错误(age 传字符串),期望 400 而非自动转换
curl -s -X POST $BASE -H "$H" \
-d '{"username":"bob","email":"b@example.com","role":"user","age":"18"}'
# 4. 越权字段(role 提权 + 多余字段),期望 400
curl -s -X POST $BASE -H "$H" \
-d '{"username":"eve","email":"e@example.com","role":"admin","is_admin":true}'
# 5. 超长与非法字符,期望 400
curl -s -X POST $BASE -H "$H" \
-d '{"username":"a<script>","email":"x@example.com","role":"user"}'
# 6. 记录校验命中量,确认拒绝确实发生在入口
grep -c INVALID_PARAM /var/log/api/access.log
第 4 条是核心用例。如果返回 201 且库里多出一个 is_admin 字段,说明 additionalProperties 没有生效,通常是因为 Schema 没被正确 include,或者校验中间件注册在路由之后。第 3 条若返回 201,说明 coerceTypes 被误开,类型混淆面已经打开。
常见问题
Schema 校验与代码里的 if 判断有什么区别?
if 判断是命令式的,规则散落在各接口,改一处漏一处;Schema 是声明式的,一份文件同时被 Node、Python、网关插件消费,规则改动只改一处。更重要的是 Schema 可以被契约测试直接读取,if 判断无法被工具自动比对。二者不冲突:Schema 负责结构与类型,业务语义(如余额充足、用户名唯一)仍要写在代码里。
开启 additionalProperties: false 会不会影响老客户端?
会,而且这是上线前必须评估的兼容性风险。建议先在日志模式运行一周:把校验失败但未拦截的请求按 path 聚合,观察是否存在历史客户端携带冗余字段。确认无影响后再切换为强制拦截,切换时给客户端预留一个版本周期的缓冲,避免移动端旧版本直接不可用。
契约测试报错但业务一切正常,是测试错了吗?
多数情况是文档滞后于实现。比如代码新增了可选字段但没写进 OpenAPI,测试按文档校验响应时会判定 response_schema_conformance 失败。这类失败恰恰是价值所在:它说明外部调用方按文档解析会拿不到新字段。处理方式是先补文档、再跑测试,不要反过来改测试跳过检查。
总结
接口参数的安全边界由三件事共同决定:契约是否完整、校验是否真的执行、实现是否与契约一致。JSON Schema 解决第一件,入口中间件解决第二件,OpenAPI 契约测试解决第三件。三者缺一,都会留下「文档很严、代码很松」的落差,而这个落差正是参数注入与越权最喜欢待的地方。落地顺序建议自上而下:先给高风险接口(登录、注册、支付、后台管理)补 Schema,再接入运行时校验,最后把契约测试塞进 CI,逐步把整套规则覆盖到全部接口。