企业官网建设流程全解析

• 后端
• 文档
• 教程

导读：本文以 system-design-101 仓库中 top-12-tips-for-api-security.md 的 12 条 API 安全清单为骨架，逐条展开讲解其在真实 Web 与微服务架构中的落地方式。读完本文，你将掌握从传输加密、认证授权、限流防刷、版本治理到网关防护、错误处理、输入校验的一整套可执行的 API 安全加固方案。

为什么 API 安全值得单独列一张清单

API 是前后端、微服务之间交换数据的主要通道，也是攻击者最容易接触到的系统入口。一个不安全的 API 可以暴露整个应用，甚至放大为数据泄露事件。基于这一共识，system-design-101 仓库在 top-12-tips-for-api-security.md 中给出了 12 条简洁的安全要点，本仓库中还有 a-cheatsheet-to-build-secure-apis.md 等文档与它互相印证。

这 12 条要点可以按防护层次分为四组，也是本文的展开结构：

• 传输与认证：Use HTTPS、Use OAuth2、Use WebAuthn、Use Leveled API Keys
• 访问控制与防滥用：Authorization、Rate Limiting、Whitelisting
• 演进与治理：API Versioning、Use API Gateway
• 健壮性兜底：Check OWASP API Security Risks、Error Handling、Input Validation

下面逐条展开。

1. Use HTTPS：加密传输是一切安全的前提

核心要点：所有 API 流量都应通过 HTTPS（TLS）传输。

• HTTPS 对传输中的数据进行加密，防止中间人（man-in-the-middle）攻击窃听报文。
• 它同时提供完整性校验，确保数据在传输途中没有被篡改。
• 在浏览器与服务器之间，TLS 通过握手协商加密套件、交换证书并验证服务器身份（https-ssl-handshake-and-data-encryption-explained-to-kids.md 对此有专门讲解）。

落地建议：仅通过 443 端口对外提供服务，对 80 端口执行 301 跳转；配置 HSTS 响应头强制客户端使用 HTTPS；不要在 URL 查询参数中放置敏感信息（它们会被记入访问日志与浏览器历史）。

2. Use OAuth2：用标准授权框架替代自造认证

核心要点：不要让用户把密码交给第三方应用，改用 OAuth2 委托授权。

OAuth2 是一个允许第三方应用在用户授权范围内访问其数据的标准框架，整个过程不需要暴露密码（oauth-2-explained-with-siple-terms.md）。一次 OAuth 授权获得的 token 可以做到：

• 单点登录（SSO）：一次登录即可访问多个服务。
• 跨系统授权：在不同系统间共享访问权限，无需重复登录。
• 受限的资料访问：只读取用户允许开放的那部分资料。

oauth-20-flows.md 列出了主要的授权流程：

• Authorization Code Flow：最常用。用户认证后，客户端先拿到授权码，再换取 access token 与 refresh token。
• Client Credentials Flow：适用于服务到服务（M2M）的调用场景。
• Implicit Flow：早期面向单页应用的简化流程，access token 直接返回客户端（官方现已不推荐）。
• Resource Owner Password Grant Flow：允许用户直接把用户名密码交给客户端换取 token，仅建议在高度可信的一方场景使用。

在 session-cookie-jwt-token-sso-and-oauth-2.md 中，仓库用一张图把 Session、Token、JWT、SSO、OAuth2 的定位讲清楚了：Session 靠服务端存储加 Cookie；Token/JWT 把身份编码进令牌，无状态但需要加解密；OAuth2 则专注于"受控授权"。

3. Use WebAuthn：无密码认证的现代选择

核心要点：用 WebAuthn（Web Authentication）为 API 与 Web 应用提供基于公钥密码学的无密码认证。

WebAuthn 的思路是：在用户的设备（如安全密钥、指纹、Face ID）上生成密钥对，私钥永不离开设备，服务器只保存公钥。认证时服务器用挑战值（challenge）验证签名，因此：

• 不存在可被钓鱼的共享口令，天然抵御撞库与中间人窃取口令；
• 认证过程不需要服务端存储明文密码，也不需要传输敏感凭证。

这与本仓库 top-4-forms-of-authentication-mechanisms.md 所介绍的多因素认证体系互补，常用于与 OAuth2、Passkey 组合实现高强度登录。

4. Use Leveled API Keys：分级 API Key，避免一把钥匙走天下

核心要点：API Key 应分级管理，不同调用方拥有不同权限与配额，而不是所有调用方共用一把全局钥匙。

常见分级维度：

• 按环境分级：开发（dev）Key、测试（staging）Key、生产（prod）Key 互相隔离，生产 Key 权限最高、配额最严格；
• 按调用方分级：内部服务、合作伙伴、第三方开发者分别使用不同 Key，便于独立限流、审计与吊销；
• 按能力分级：只读 Key、读写 Key、管理 Key 分层签发，最小权限原则落地。

落地建议：Key 本身不是认证终点，应配合 IP 白名单、签名或 OAuth token 使用；Key 泄露时能单独吊销而不影响其他调用方。

5. Authorization：认证之后，必须再做授权

核心要点：认证（Authentication）回答"你是谁"，授权（Authorization）回答"你能做什么"，两者必须分离并都执行。

• 不要只依赖"是否登录"来判断，要校验请求者对具体资源的访问权限；
• 优先采用基于角色的访问控制（RBAC），按角色统一管理权限，减少未授权操作风险（a-cheatsheet-to-build-secure-apis.md）；
• 对细粒度场景可叠加基于属性的策略，防止水平越权（用户 A 访问用户 B 的资源）与垂直越权（普通用户调用管理员接口）。

落地建议：在每个受保护接口入口统一执行授权校验，不要散落在业务代码里；OAuth2 的 scope 也可以用来表达授权范围，与 RBAC 配合使用。

6. Rate Limiting：限流是防刷与抗 DoS 的第一道闸

核心要点：通过限流限制单个 IP 或单个用户在一定时间窗口内的请求次数，防止 DoS 攻击、暴力破解与接口滥用，同时保证系统公平性（a-cheatsheet-to-build-secure-apis.md）。

限流需要回答三个问题：

• 按谁限：按 IP、用户、API Key 还是设备指纹；
• 按什么算法：固定窗口、滑动窗口、令牌桶、漏桶（仓库 top-6-load-balancing-algorithms.md 涉及相关思路，the-ultimate-redis-101.md 则展示了用 Redis 实现分布式限流的常见做法）；
• 超限怎么办：返回 429 Too Many Requests，并带上Retry-After响应头告知客户端何时可重试。

落地建议：对登录接口单独设置更严格的限流，因为它是暴力破解的主要目标；限流规则建议收敛在 API 网关统一执行。

7. API Versioning：版本化是安全演进的前提

核心要点：API 会持续演进，直接原地修改接口会破坏既有调用方，也会让老客户端带着旧漏洞长期存在。版本化让新老行为并行、可灰度、可下线。

常用版本策略：

• URI 路径版本：/api/v1/orders、/api/v2/orders，最直观、最常用；
• 请求头版本：Accept: application/vnd.company.v2+json，路径保持干净；
• 查询参数版本：?version=2，实现简单但对缓存不友好。

落地建议：明确版本的生命周期与弃用策略，老版本到期后强制下线；对新版本做安全回归测试，避免"新功能上线、旧漏洞随行"。

8. Whitelisting：白名单收紧入口

核心要点：默认拒绝、显式放行，是比黑名单更安全收敛的防护思路。

可白名单化的对象包括：

• 允许的请求源/域名：通过 CORS 白名单控制浏览器跨域访问；
• 允许的调用方 IP：管理端与内部接口只对特定网段开放；
• 允许的 HTTP 方法：接口只开放实际需要的 GET/POST/PUT/DELETE，关闭其余方法；
• 允许的字符集与枚举值：对请求字段做白名单校验，而非黑名单过滤。

API 网关在这一层常执行 allow-list/deny-list 检查（what-does-api-gateway-do.md 的 Step 3）。

9. Check OWASP API Security Risks：以行业标准自查

核心要点：以 OWASP（Open Web Application Security Project）维护的 API Security Top 10 为基准，对 API 做周期性安全评审。

自查清单通常覆盖：

• BOLA/IDOR（对象级越权）：能否通过修改资源 ID 访问他人数据；
• 对象属性级授权失效：能否越权读写额外字段；
• 过度数据暴露：响应是否返回了比需求更多的字段；
• 资源消耗与无限制请求：是否缺少配额与限流；
• 认证失败与授权失效：认证机制是否可被绕过；
• SSRF：服务端请求是否可被诱导访问内网资源。

落地建议：把 OWASP Top 10 融入上线前的安全评审 checklist，并在每次接口变更后复查受影响条目。

10. Use API Gateway：把安全策略收敛到统一入口

核心要点：API 网关位于客户端与后端服务之间，是执行安全策略的统一入口，避免每套微服务各自实现一套残缺的防护。

结合 api-gateway-101.md 与 what-does-api-gateway-do.md，网关在安全上承担的关键职责包括：

• Step 2：解析并校验 HTTP 请求中的属性；
• Step 3：执行 allow-list/deny-list 白名单检查；
• Step 4：对接身份提供方（Identity Provider）完成认证与授权；
• Step 5：应用限流规则，超限即拒绝请求；
• Steps 6-7：按路径匹配把请求路由到对应服务；
• Step 8：按需做协议转换再转发到后端；
• Steps 9-12：统一处理错误、故障熔断（circuit break）、日志监控（如 ELK）与缓存。

此外网关还承担负载均衡、API 组合与缓存等功能（api-gateway-101.md）。把 HTTPS 终止、限流、鉴权、白名单全部收敛到网关，是"集中管控、后端瘦身"的关键一步。

11. Error Handling：错误信息也会泄露攻击面

核心要点：错误处理不当会向攻击者泄露内部实现细节（堆栈、SQL、依赖版本、文件路径），成为侦察阶段的免费情报。

错误处理原则：

• 统一错误响应结构：固定使用{ "error": { "code", "message", "details" } }之类的标准格式；
• 对内记录、对外模糊：详细堆栈写日志与监控，响应给客户端的是脱敏后的通用信息；
• 区分语义码：用标准 HTTP 状态码表达语义，如 400（参数错误）、401（未认证）、403（未授权）、404（不存在）、429（限流）、500（服务端错误）；
• 不泄露敏感数据：日志中不得记录信用卡号、密码、凭据等（a-cheatsheet-to-build-secure-apis.md 同样强调"Don't log sensitive data"）。

落地建议：对异常做全局兜底处理，确保任何未捕获异常都不会以原始堆栈形式出现在 HTTP 响应中。

12. Input Validation：输入校验是最后一道防线

核心要点：对所有进入系统的数据（参数、请求体、请求头、路径变量、查询字符串）做校验，防御注入攻击与异常数据格式（a-cheatsheet-to-build-secure-apis.md）。

校验要点：

• 类型与长度：字段类型、长度、取值范围在进入业务逻辑前先行校验；
• 内容白名单：枚举值、字符集做白名单约束；
• 防注入：对 SQL、NoSQL、命令与模板注入场景，配合参数化查询与转义使用；
• 防御异常载荷：限制请求体大小，拒绝畸形 JSON/XML，防止解析器被攻击。

输入校验应发生在最靠近边界的位置（网关或框架层），而不是等到业务代码深处才发现数据不合法。

把 12 条要点串成一条纵深防线

以上 12 条不是孤立的技巧，而是一条"纵深防御（defense in depth）"链路，从外到内依次是：

1. 传输层：HTTPS（第 1 条）保证流量可信；
2. 入口层：API 网关（第 10 条）统一执行白名单（第 8 条）、限流（第 6 条）与错误收敛（第 11 条）；
3. 身份与权限层：OAuth2（第 2 条）、WebAuthn（第 3 条）、分级 API Key（第 4 条）负责认证，Authorization/RBAC（第 5 条）负责授权；
4. 数据与逻辑层：输入校验（第 12 条）守住业务边界；
5. 治理与进化层：API 版本化（第 7 条）保证安全演进，OWASP 自查（第 9 条）让防线随威胁持续更新。

对任意一个新 API，都可以把这张清单当作上线前的安全检查表：传输加密了吗？认证授权分离了吗？限流配额配了吗？错误信息脱敏了吗？输入校验做了吗？逐条对过，API 的安全基线就基本立住了。system-design-101 仓库中的 top-12-tips-for-api-security.md 正是这样一个可随手引用的起点，配合 a-cheatsheet-to-build-secure-apis.md、oauth-20-flows.md、api-gateway-101.md 等文档，可以继续深入到每个子主题。

• 后端
• 文档
• 教程