📚 课程目录第2章权限模型基础

2. 权限模型基础

排障的第一步不是看日志，而是先弄清楚“请求到底在哪一关卡住了”。行情接口的权限体系并不是一个单一开关，而是一条从身份确认到资源放行的链路：认证（Authentication）回答“你是谁”，授权（Authorization）回答“你能访问哪些行情资源”，鉴权（Access Control / 校验执行）则是在每次请求到达时，把凭证、权限范围、配额与资源策略逐项比对并给出放行或拒绝的结论。三者混淆，就会把 401 当成 403 处理，或把 429 误判为权限不足，排障方向立刻跑偏。

一、认证、授权与鉴权在链路上的位置

以常见的 REST/WebSocket 行情接口为例，一次订阅请求通常依次经过：凭证解析（API Key、Token、签名）→ 身份认证 → 权限范围校验（是否开通该市场、该品种、该频次）→ 配额与限流检查 → 资源路由与数据返回。认证失败通常返回 401，表示凭证缺失、过期、签名错误或身份无法识别；授权失败返回 403，表示身份已确认，但该身份没有访问目标行情资源的权限，例如未开通港股 Level-2、未订阅某交易所深度数据、IP 不在白名单；429 则属于配额/限流层面的拒绝，身份和权限都可能正确，只是请求速率或并发数超过了约定阈值。

需要特别强调边界：401 是“身份未通过”，403 是“身份通过但权限不足”，429 是“权限通过但节奏超限”。三者对应的修复动作完全不同——401 要检查密钥、签名、时间戳与 Token 有效期；403 要检查套餐、市场权限、IP 白名单与资源路径；429 要检查 QPS、并发连接数、订阅数量与退避策略。把 429 当 403 去申请权限，或把 403 当 401 去换密钥，都是典型误判。

二、常见错误码的语义与边界

除了 401、403、429，行情接口还会出现 400（请求参数不合法，如合约代码格式错误、时间区间非法）、404（资源不存在，如合约已下架或路径拼写错误）、5xx（服务端异常）。这些码与权限无关，但在排障时经常与权限问题混在一起。判断原则是：先看状态码大类，再看响应体中的错误码与 message 字段。很多行情服务会在 403 的响应体里给出更细的业务码，例如“MARKET_NOT_SUBSCRIBED”“IP_NOT_ALLOWED”“LEVEL2_REQUIRED”，这些业务码才是定位具体权限项的关键。

以某行情服务为例，其响应体可能形如：

{
  "code": 40301,
  "message": "market permission denied",
  "detail": "HK_LEVEL2 not subscribed for account A1024",
  "request_id": "req_7f3c9a"
}

此时 HTTP 状态是 403，但真正要处理的是 HK_LEVEL2 这个权限项，而不是去换 API Key。反过来，如果返回 401 且 detail 为“signature mismatch”，则应检查签名算法、参数排序与密钥版本，而不是去申请行情套餐。排障时把 HTTP 状态码与业务错误码分开记录，能显著减少误判。

三、鉴权链路上的关键参数与检查点

认证环节常见参数包括 API Key、Secret、签名（HMAC-SHA256 或 RSA）、时间戳、随机串 nonce。签名通常按“请求方法 + 路径 + 排序后的参数串 + 时间戳 + nonce”拼接后计算，任何一项顺序或编码不一致都会导致 401。授权环节常见参数包括账户 ID、套餐等级、市场列表、品种白名单、IP 白名单、订阅频段（Level-1/Level-2、逐笔/快照）。配额环节常见参数包括每秒请求数 QPS、并发连接数、单连接订阅标的数、历史数据单次查询区间。把这些参数整理成一张检查表，排障时按链路顺序逐项核对，比盲目重试有效得多。

建议在客户端日志中同时记录：HTTP 状态码、业务错误码、request_id、请求路径、关键参数摘要（不要记录完整 Secret）、时间戳与重试次数。这样在对照服务端日志时能快速定位是认证、授权还是限流环节。

四、一个可复用的排障判断顺序

拿到一次失败请求后，建议按以下顺序判断：第一步看 HTTP 状态码属于 4xx 还是 5xx；第二步若是 401，核对凭证与签名，确认时间戳偏差在允许范围内；第三步若是 403，读取业务错误码，定位到具体权限项（市场、品种、IP、套餐），并确认账户状态是否正常；第四步若是 429，读取 Retry-After 响应头，检查当前 QPS 与并发连接数，必要时合并订阅、降低轮询频率、增加退避；第五步若状态码正常但数据为空，则问题可能不在权限链路，而在合约代码、时间区间或数据源本身。这个顺序的价值在于：它把“权限问题”与“参数问题”“服务端问题”分开，避免在错误的方向上反复尝试。

最后要建立边界意识：401 与 403 的分界是“身份是否被确认”，403 与 429 的分界是“权限是否足够”与“节奏是否合规”。同一账户在不同时间可能先遇到 429、再遇到 403，也可能因为 Token 刷新失败而出现 401，排障记录中应保留每次请求的完整上下文，而不是只记一个状态码。理解这条链路，后续面对具体案例时才能快速判断该查凭证、查权限还是查限流。