# API网关配置Skill

> 网关路由、鉴权、限流、熔断、日志的配置规范。当需要配置 API 网关(路由转发、统一鉴权、限流熔断、访问日志)时使用。

- Skill: `sky-cube/api-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sky-cube/api-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sky-cube/api-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Sky-Cube (https://skillmd.com/u/sky-cube)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sky-cube/api-skill

---

# API网关配置Skill

## 适用场景
配置 API 网关:路由与转发规则、统一鉴权、限流、熔断降级、访问日志与安全基线。

## 执行步骤
1. 网关选型:按团队栈选择 Nginx/Spring Cloud Gateway/Kong/APISIX 等主流方案,功能(动态路由/插件生态/运维成本)与现状匹配。
2. 路由配置:按服务划分路由前缀,重写规则、超时、负载均衡策略明确;路由变更走配置版本化,禁止无记录线上热改。
3. 鉴权:统一在网关校验 JWT/OAuth2 Token,仅白名单路径免鉴权且白名单最小化;下游服务不重复信任裸请求,内部调用走内部鉴权或网络隔离。
4. 限流:按用户/接口/IP 分级限流(令牌桶等主流算法),限流响应码统一(如 429),业务错误不误用限流码。
5. 熔断与降级:下游异常率/慢调用阈值触发熔断,降级返回兜底响应;恢复探测(半开)配置齐全。
6. 日志:访问日志含 traceId/用户/路径/耗时/状态码,响应体不落敏感数据,日志脱敏后输出;关键操作审计。
7. 安全基线:请求体大小限制、超时上限、CORS 白名单、防重放(需验证适用性)、禁止透传敏感 header。

## 规范要点
- 鉴权必须收敛在网关,但网关不替代业务侧权限校验(网关管身份,业务管权限)。
- 免鉴权白名单定期评审,禁止大范围放行。
- 密钥与证书禁止写入网关配置明文,走配置中心/密钥管理,配置仓库中不落真实密钥。
- 限流阈值基于压测数据设定,上线后按监控调优,禁止拍脑袋固定。
- 熔断必须有降级响应,禁止熔断后直接抛错误码无兜底文案。
- 网关自身高可用:多实例+健康检查,单点不可接受。

## 输出模板
```
## 网关配置方案
选型与拓扑:网关/版本/实例数/高可用
路由表:路径前缀/下游服务/重写规则/超时
鉴权配置:校验方式/白名单清单/Token 校验点
限流熔断:接口分级阈值表 + 熔断参数 + 降级响应
日志与安全:traceId 注入/脱敏规则/安全基线清单
```

## 自检清单
- [ ] 路由与重写规则有版本化记录
- [ ] 鉴权收敛网关,白名单最小化
- [ ] 密钥证书无明文落配置
- [ ] 限流阈值有压测依据,熔断有降级兜底
- [ ] 日志含 traceId 且敏感信息已脱敏