Skip to content

接口与流量入口设计 ​

本篇要点:画出请求进入业务服务之前的四层判断,并为每一层写出可核对的职责边界。前置文章:[《高可用:冗余、故障域与多活容灾》](/guide/architecture/high-availability-multi-active.html)讲的是单点故障怎么被冗余和故障域挡住,那时我们默认请求已经进了系统,这一章往上游走一步。

一、为什么需要它 ​

2026 年 3 月,一个日订单四万左右的电商团队做 App 改版。客户端同学提了个需求:首页现在要串行发六个请求(商品、库存、优惠券、推荐、公告、用户资产),弱网下首屏 3.2 秒,能不能给一个聚合接口一次返回?

后端一周内交付了 /api/home/aggregate。上线三周,三个问题陆续出现。

库存服务一次 8 秒的超时,把首页可用性从 99.95% 拉到 98.7%,因为这个聚合接口串行调用六个下游,任何一个慢都拖住整页。优惠券团队改了一个字段名,聚合接口要跟着发版,而发版窗口一周只有两次。运营在网关里加了一段 Lua 做活动页跳转,半年后这段代码 800 行,没人敢删。

这三个问题的位置相同:入口层没有分层,路由、认证、聚合、业务规则搅在一处。判断一段逻辑该放哪,只需要问一句——换了调用方它还成立吗。「满 199 减 30 这张券能不能用」换哪个客户端都成立,它属于券服务;「iOS 端不返回某字段」只对 iOS 成立,它属于 BFF。这条线画不清,网关就会长成第二个业务系统。

二、核心概念 ​

2.1 先定风格,再定契约 ​

API 风格(API style)是接口长什么样的一组约定,三种主流各有适用面。

风格契约怎么描述传输与编码浏览器可直连适合的场景
RESTOpenAPI(YAML/JSON)HTTP/1.1 或 HTTP/2,JSON 为主是面向第三方、资源模型清晰、要吃 CDN 缓存
gRPCProtobuf .protoHTTP/2,二进制否,需 gRPC-Web 或代理服务间调用、强类型、双向流
GraphQLSDL schemaHTTP,JSON是客户端字段需求差异大、聚合多源

表 7-1 三种 API 风格的契约描述、传输方式与适用面

REST 的价值不在「用 GET 和 POST 传 JSON」,在于 HTTP 语义被链路上每一层信任:GET 幂等(idempotent,重发多次结果一样)可缓存,PUT 幂等可重试,POST 不幂等不能被自动重试。网关、CDN、浏览器、HTTP 客户端库全都按这套语义行事。把「下单」写成 GET,等于告诉每一层「这个请求重发几次都没关系」。

契约优先(contract-first)指的是先写 OpenAPI 或 .proto,再从它生成服务端骨架与客户端 SDK。反过来的做法是先写 Controller、用注解生成文档,文档永远是实现的下游:实现一改文档就漂,而消费方还在按文档写代码。截至 2026 年 11 月,OpenAPI 3.1.0(2021 年 2 月发布)仍是工具链兼容性最好的版本,它对齐 JSON Schema 2020-12 的 oneOf 与可空语义,这一点 3.0.x 表达不了。

2.2 网关只做横切,不做编排 ​

API 网关(API Gateway)是所有外部流量的唯一入口。它该做横切关注点(cross-cutting concerns):TLS 终止、路由、认证、粗粒度限流、熔断、灰度分流、访问日志。

不该做的是三件事:业务编排、跨服务事务、数据聚合。

图 7-1 一次外部请求经过的四层,以及网关不该跨过的那条线

如图 7-1 所示,BFF 与业务服务都在网关后面,位置相近但面向不同:BFF 面向某一类客户端,业务服务面向某一类领域规则。

2.3 认证放在网关,授权留在服务 ​

认证(authentication)回答「你是谁」,授权(authorization)回答「你能做什么」。前者可以集中,后者不行。

主流做法是 OIDC(OpenID Connect,架在 OAuth 2.0 之上的身份层):客户端拿 access token,网关校验签名,把 sub 和 scope 透传给下游。截至 2026 年 11 月,OAuth 2.1 仍是 IETF 草案(draft-ietf-oauth-v2-1),没有正式 RFC,生产上依旧是 OAuth 2.0 加 PKCE(RFC 7636)。

**网关能判的是粗粒度:签名有效、未过期、scope 里有 order:write;它判不了「这个用户是不是这笔订单的持有人」。**后者必须回业务服务查,因为「谁是持有人」是领域规则,会随业务变化,而网关不该跟着改。

反例:把角色列表塞进 JWT 且有效期 24 小时。运营在后台撤权后,当事人在接下来 24 小时里照样能调接口。缓解办法是缩短 access token 寿命到 5–15 分钟、用 refresh token 续期,或者在网关比对 token 版本号,撤权时把版本号加一。

2.4 限流保护的是自己 ​

限流(rate limiting)的目的不是惩罚调用方,是在下游被压垮前主动拒掉一部分请求。四个算法的差别在「允不允许突发」和「计数精度」。

算法怎么计数允许突发主要问题
固定窗口每个时间窗内累加,窗口结束清零是窗口边界处实际通过量可达上限的两倍
滑动窗口按最近 N 秒加权计数是内存与计算开销随精度上升
令牌桶按速率补令牌,桶有容量上限是,上限即桶容量两个参数,容易配歪
漏桶请求排队,按恒定速率流出否,只排队不拒绝排队延迟会叠进 p99

表 7-2 四种限流算法的计数方式与副作用

固定窗口的边界突刺是真事:窗口一分钟、配额 100,在 00:59 打 100 个、01:00 再打 100 个,两秒内过了 200 个。令牌桶是多数网关的默认项,因为「每秒 100 个、允许 20 个突发」这种话业务方能听懂。

维度比算法更容易出错。按 IP 最便宜,但一个公司出口 NAT 后面可能是八千个用户,限流一开就是整栋楼遭殃。按用户或租户更准,代价是先解 token,而解 token 发生在认证之后。按接口限流保护的是热点,比如商品详情。

还有一处只在多副本时才暴露:单机限流等于把配额乘以副本数。你要的是全局 1000 QPS,部署 10 个副本、每个配 100,滚动发布时副本数短暂变成 4,全局配额就掉到 400。全局限流需要共享计数器,见 3.2 节。

2.5 版本号不等于兼容 ​

语义化版本(Semantic Versioning)是给库用的,API 不完全适用。API 版本策略有三种常见做法:路径里带(/v2/orders)、Header 里带(Accept: application/vnd.shop.v2+json)、不带版本号只做增量演进。

真正决定能不能改的是兼容规则,不是路径里有没有 v2。

变更兼容吗原因
新增可选请求字段兼容老客户端不传,服务端走默认值
新增响应字段有条件兼容前提是消费方忽略未知字段,严格校验的客户端会崩
可选字段改为必填不兼容老客户端不传就是 400
字段类型 int 改 string不兼容反序列化直接失败
字段名不变、语义改变最危险编译通过、测试通过、线上算错钱

表 7-3 六类接口变更的兼容性判定

弃用要走流程,不能只发公告。RFC 8594(2019 年 5 月,Informational)定义了 Sunset 响应头,RFC 9745(2025 年 3 月,Standards Track)定义了 Deprecation 头。这两个头的时间格式不一样,写错一个是常见事故:Deprecation: @1688169599 用 Unix 秒并带 @ 前缀,Sunset: Sun, 30 Jun 2024 23:59:59 GMT 用 HTTP-date。更实际的动作是:先加监控看调用量,再按客户端版本灰度关停,最后才删代码。调用量 0.3% 的接口不能直接下线,那 0.3% 里往往是某个没升级的大客户。

2.6 BFF:一个前端一个后端 ​

BFF(Backend for Frontend)是为某一类客户端定制的聚合层。移动端要精简字段省流量,Web 端要一次拿全,后台管理系统要联表查询。三类需求硬塞进一个接口,结果是返回 200 个字段、每个客户端只用 20 个。

BFF 的代价是多一层部署、多一处发版。它适合前端形态差异大、聚合逻辑频繁变化的场景;如果三个客户端要的数据九成相同,加 BFF 只是多了一个要发版的地方。

三、动手实践 ​

两个可复现的实验:先用 Nginx 看清限流的默认状态码,再用 Redis 令牌桶做一次全局限流。

3.1 边缘限流:默认状态码是 503 ​

nginx
# nginx.conf 的 http 块;limit_req_status 从 nginx 1.3.15 起可用,add_header 的 always 从 1.7.5 起可用
limit_req_zone $binary_remote_addr zone=perip:10m rate=5r/s;

server {
    listen 8080;
    location /api/ {
        limit_req zone=perip burst=10 nodelay;
        limit_req_status 429;          # 默认是 503
        add_header Retry-After 1 always;
        proxy_pass http://backend;
    }
}

rate=5r/s 是每秒补 5 个令牌,burst=10 允许 10 个排队的突发,nodelay 让突发立即通过而不是按队列延迟。把那行 limit_req_status 注释掉,被限的请求会返回 503。

运行结果(hey -z 10s -c 20 http://127.0.0.1:8080/api/ping,节选):

text
Summary:
  Total:        10.0213 secs
  Requests/sec: 187.4021

Status code distribution:
  [200] 62 responses
  [429] 1816 responses

10 秒里放过去约 60 个请求(5 × 10 加 10 个突发),其余全被拒。数字本身随机器波动,要看的是一件事:默认的 503 会让不少 HTTP 客户端判定为服务端故障并自动重试,重试打回来又是一轮限流,把一次过载拖成雪崩。429 加 Retry-After 才表达得出「你被限了,等一会儿再来」。

3.2 全局限流:把计数器放进 Redis ​

python
# rate_limit.py —— Python 3.11 / redis-py 5.0.x / Redis 7.4.x
import time
import redis

LUA = """
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill = tonumber(ARGV[2])   -- 每秒补充的令牌数
local now = tonumber(ARGV[3])
local ttl = tonumber(ARGV[4])

local data = redis.call('HMGET', key, 'tokens', 'ts')
local tokens = tonumber(data[1])
local ts = tonumber(data[2])
if tokens == nil then
  tokens = capacity
  ts = now
end
local delta = math.max(0, now - ts) * refill
tokens = math.min(capacity, tokens + delta)
local allowed = 0
if tokens >= 1 then
  tokens = tokens - 1
  allowed = 1
end
redis.call('HSET', key, 'tokens', tokens, 'ts', now)
redis.call('EXPIRE', key, ttl)
return allowed
"""

r = redis.Redis(host="127.0.0.1", port=6379, decode_responses=True)
script = r.register_script(LUA)          # 用 EVALSHA,脚本只传一次

def allow(user_id, capacity=5, refill=0.4):
    return script(keys=[f"rl:{user_id}"], args=[capacity, refill, time.time(), 60]) == 1

for i in range(20):
    print(i, "allow" if allow("u-42") else "deny")
    time.sleep(0.2)

运行结果:

text
0 allow
1 allow
2 allow
3 allow
4 allow
5 deny
6 deny
7 deny
8 deny
9 deny
10 deny
11 deny
12 deny
13 allow
14 deny
15 deny
16 deny
17 deny
18 deny
19 deny

手算一遍就明白为什么后面连拒八次。容量 5,每 0.2 秒补 0.2 × 0.4 = 0.08 个令牌:i=0 到 i=4 放行五次,桶里只剩 0.32 个;i=5 时桶里只有 0.4 个,之后每次涨 0.08,涨到 i=13 时的 1.04 个才够放行一次,放完剩 0.04。中间那八次不是随机拒的,是令牌还不够一个。浮点累加可能让放行位置前后挪一位。

关键在于这段逻辑跑在 Redis 里:HMGET 读到写回之间没有间隙,十个应用副本共享同一个桶。放到应用内做,每个副本各有一个桶,全局配额就变成了副本数的倍数。

四、常见误解 ​

很多人以为 REST 就是「用 GET 查、用 POST 改」,实际上风格的价值在幂等语义被中间层信任。GET 可以重试、可以缓存、可以被 CDN 折叠,POST 都不行;把写操作塞进 GET,链路上任何一层重试都可能多下一单。

很多人以为限流开了就安全,实际上单机限流的额度会随副本数漂移。滚动发布、弹性扩缩、灰度多版本并行,任何一种都会让「每副本 100 QPS」这句话失去意义,而扩容恰恰发生在流量上涨的时候。

很多人以为版本号是兼容性的解法,实际上 /v2/ 只解决了「两套接口同时存在」,解决不了「v2 内部能不能改字段」。是否需要升版本取决于 2.5 节那张表,与路径里有没有 v2 无关;路径分段真正的成本是它把同一份业务逻辑复制了两遍。

五、小结 ​

[《高可用:冗余、故障域与多活容灾》](/guide/architecture/high-availability-multi-active.html)解决了「系统里坏一台机器会怎样」,这一章解决「请求从外面进来时经过谁的手」。

  • 入口分四层:边缘(DDoS、TLS)、网关(路由、认证、粗粒度限流)、BFF(按客户端聚合)、业务服务(领域规则)。判断归属只需问「换了调用方它还成立吗」。
  • 契约优先,风格服务于调用方:对外用 REST 加 OpenAPI,服务间用 gRPC 加 Protobuf,风格定完再谈实现。
  • 认证可以集中,授权必须分散。JWT 里的权限在有效期内无法撤销,短令牌加版本号是代价最小的补救。
  • 限流要区分维度与作用域,多副本下必须走共享计数器;被限时返回 429 加 Retry-After,别用默认的 503。
  • 兼容性由变更类型决定,不由版本号决定;弃用要看调用量,不能只发公告。

六、相关文章 ​

入口层收紧之后,网关成了所有请求的必经点,也成了埋第一行指标最合适的位置。但指标本身不产生判断——[《可观测性与 SLO:用数据管架构》](/guide/architecture/slo-error-budget.html)要回答的是:99.95% 这个数字怎么定义、错误预算烧到什么程度该冻结发布、以及一次故障里怎么用数据把范围从「全站」收敛到「一个 span」。

继续阅读:[《可观测性与 SLO:用数据管架构》 可观测性与 SLO:用数据管架构](/guide/architecture/slo-error-budget.html)