API 网关
HTTP 入口：认证、签名、访问控制与可观测性
项目背景
同一个网关服务于终端用户应用、租户/合作伙伴后台，后来还有一个外部管理 API。每条路由需要不同的认证、租户解析、访问控制和可观测性组合，而每个下游服务都需要知道调用方是谁，以便审计。
架构设计
客户端 → Gin 中间件链（日志/恢复 → 链路追踪 → 指标 → 域名/租户解析 → token 认证 → 账号状态 → 黑白名单 → IP 策略）→ handler 校验输入、检查权限并扇出调用 gRPC 服务 → 按客户端重塑响应。认证中间件将操作员、IP、路径、租户和 trace ID 写入外发的 gRPC metadata。
核心技术亮点
初版中间件：注入用户上下文的 token 认证、请求签名校验、多维度黑白名单、域名到租户的解析、IP 策略、带 panic 恢复的结构化日志、OpenTelemetry 链路追踪和 Prometheus 指标
后续新增：所有需认证路由上的账号状态守卫、按平台的域名开关，以及在每次下游 gRPC 调用上附带操作员/租户/trace 元数据
面向合作伙伴网络的分层、字段级授权：操作员只能操作自己下级的账号，敏感字段（风险等级、绑定 IP、密码）有独立的权限
后台响应中的 PII 脱敏；跨服务账号创建的补偿回滚
跨服务的列表筛选条件先解析为 ID 集合，再并行执行
核心实现
可组合的中间件链
每个横切关注点都是独立的 Gin 中间件，路由组只启用自己需要的策略。
Why: 终端用户、后台和集成路由的安全需求各不相同；关注点分离让 handler 保持精简。
每次下游调用都携带调用方身份
认证通过后，中间件将操作员 ID、客户端 IP、HTTP 路径、租户和 trace ID 作为外发 gRPC metadata 附加到请求上。
Why: 这样任何下游服务都能记录可追溯到具体操作人的审计事件或链路追踪，而无需重新推断调用方身份。
Result: 这成为全平台审计追踪的基础（见审计日志服务）。
分层授权
一套权限检查：平台管理员可在任意范围操作，会员无权访问，其他操作员只能操作合作伙伴树中位于自己下级的账号。主账号与子账号、各个敏感字段另有独立规则。
Why: 在多级合作伙伴网络中，“能否编辑用户”还不够，关键在于能编辑谁的用户。
技术决策
| 技术决策 | 选择 | 替代方案 | 原因 |
|---|---|---|---|
| 框架 | Gin | go-zero REST | Gin 的中间件链可按路由组进行细粒度控制，在边缘层这比代码生成更重要。 |
| 在哪里解析调用方 | 在网关解析一次，通过 gRPC metadata 向下传递 | 每个服务各自重新校验 token | 每个请求只校验一次，日志、链路追踪和审计事件使用同一个一致的身份。 |