--- title: "接口安全实践：从传输通道、入口到数据输出的全链路防护" description: "接口安全技巧，按请求链路从传输通道、入口、业务逻辑排到数据输出与运营治理，附 Spring Boot 代码示例与落地检查清单。" published: 2026-07-14T00:00:00.000Z category: "学习文档" tags: ["接口安全","Web安全","Spring Boot","最佳实践"] canonical: https://tblog.mmzhiku.xyz/posts/details-api-security-practices/ --- > [!NOTE] 提示 > 接口安全不是单项措施，而是一张按请求链路展开的措施清单。本文按传输通道、入口、业务逻辑、数据与输出、横切运营整理了 20 个技巧，每个统一按「防什么 / 怎么做 / 边界在哪」三段拆解并附 Spring Boot 代码示例。威胁分类以 OWASP API Security Top 10（2023）为准。 ## 引子 一个典型的上线场景：电商小程序发版，团队把 HTTPS 配好、前端表单校验做完，接口联调通过就上了线。两周后接连出三件事：安全公司渗透测试用改 `orderId` 的方式遍历出了全站订单数据；短信验证码接口被脚本刷掉 3000 条费用；评论区被塞满了赌博广告。三个问题对应三件没做的事：对象级鉴权、频控加验证码、敏感词过滤。 这个组合很典型。团队不是没听过这些词，而是没有把「安全」当成一张可以逐项勾选的工程清单去落地。OWASP 把「改个 ID 就能看别人数据」这类漏洞排在 API Security Top 10（2023）的第一位（API1:2023 BOLA）；Salt Security 的统计里，与对象级鉴权相关的攻击约占全部 API 攻击的 40%（来源：Salt Security，2023 年度攻击趋势口径）。 ## 核心摘要 - 20 个技巧按请求链路分布在五个位置：传输通道（HTTPS、签名防重放）、请求入口（IP 白名单、限流、验证码）、业务逻辑（鉴权、参数校验、文件上传、转义、SSRF、回调验签、幂等、敏感词）、数据与输出（加密、脱敏、统一返回值、CORS），以及横切的运营项（风控、审计日志、资产治理）。任何单项都能被绕过，安全来自按层组合。 - 每项按「防什么 / 怎么做 / 边界在哪」三段展开。判断一项措施是否落地的标准是：能指到具体的代码或配置，能说清它防不了什么。 - 最容易漏的是请求完整性四项：签名防重放、幂等、SSRF 防护、回调验签。HTTPS 防第三方窃听，防不了持有合法通道的人重放请求；重试和重复点击不是攻击，同样能造成重复扣款。 - 验证码策略、敏感词库、风控规则、证书这四类措施属于持续运营项，配置完不再迭代等于逐渐失效。 - 代码示例基于 Spring Boot 3.x + Redis；结论性数据标注了来源。 ## 背景知识：攻击面与防御分层 接口面对的攻击与风险可以归成十类，每一类对应一个或多个技巧。先看全景再看单项，落地的优先级会清晰很多： | 攻击与风险 | 典型手法 | 主要对策（本文序号） | |---------|---------|---------------------| | 传输窃听与篡改 | 中间人、运营商劫持、改参数、重放 | HTTPS（1）、签名防重放（2） | | 注入与恶意文件 | SQL 注入、XSS、WebShell | 参数校验（7）、转义（9）、文件上传（8） | | 越权与跨域滥用 | 改 ID 取数、调管理接口、跨域带凭证 | 权限控制（6）、CORS（17） | | 重复执行 | 抓包重发、超时重试、双击提交 | 签名防重放（2）、幂等（12） | | 服务端与回调伪造 | SSRF 打内网、伪造支付回调 | SSRF 防护（10）、回调验签（11） | | 自动化滥用 | 撞库、短信轰炸、CC、爬虫 | 验证码（5）、限流（4）、IP 白名单（3） | | 信息与数据泄露 | 堆栈外泄、拖库、返回值带敏感字段 | 统一返回值（16）、加密（14）、脱敏（15） | | 内容合规 | 违禁词、诈骗导流 | 敏感词（13） | | 批量牟利 | 羊毛党、批量注册、恶意退款 | 风控（18） | | 暴露面失控与无法追溯 | 影子接口、调试端点泄露、操作无据可查 | 资产治理（20）、审计日志（19） | 把 20 个技巧按请求链路近似归位，就是一张分层防御图（SSRF 防护管出站请求、回调验签管第三方入站，图中单独标注）。风控、审计日志与资产治理贯穿各层： ```mermaid flowchart TD A[客户端请求] --> B[通道层：1. HTTPS / 2. 签名防重放] B --> C[入口层：3. IP 白名单 / 4. 限流 / 5. 验证码] C --> D[业务层：6. 鉴权 / 7. 参数校验 / 8. 文件上传 / 9. 转义 / 12. 幂等 / 13. 敏感词] D --> E[数据与输出层：14. 加密 / 15. 脱敏 / 16. 统一返回值 / 17. CORS] T[第三方系统] -->|11. 回调验签| D D -->|10. SSRF 防护| N[(内网与外部资源)] R[横切运营：18. 风控 / 19. 审计日志 / 20. 资产治理] R -.-> C R -.-> D ``` OWASP API Security Top 10（2023）是这份清单的权威参照：API1 BOLA（对象级越权）、API2 身份认证缺陷、API3 对象属性级越权、API4 资源无限制消耗、API5 功能级越权、API6 敏感业务流无限制访问、API7 SSRF、API8 安全配置错误、API9 资产管理不当、API10 不安全地调用第三方 API。20 个技巧对 10 类威胁全覆盖：API1 与 API5 对应权限控制（6），API2 对应验证码（5）与签名（2），API3 对应脱敏（15），API4 对应限流（4），API6 对应风控（18），API7 对应 SSRF 防护（10），API8 对应统一返回值（16）与 CORS（17），API9 对应资产治理（20），API10 对应回调验签（11）。 ## 20 个技巧逐一展开 以下按一次请求的旅程排序：请求先过通道与入口，再进业务逻辑，然后落数据、出响应，运营型措施全程横切。每个技巧统一按三段介绍：**防什么**（对应的攻击与事故）、**怎么做**（生产级实现与代码）、**边界在哪**（它防不了什么、常见的错误用法）。 ### 1. 使用 HTTPS 协议 **防什么**：传输层的三类攻击：窃听（同一 WiFi 抓包直接拿走账号密码与 token）、篡改（运营商链路注入脚本或广告）、仿冒（假域名钓鱼站）。明文 HTTP 下三者都是低成本攻击，HTTPS 的 TLS 层用证书认证服务端身份、用对称加密保护数据、用 MAC 保证完整性。 **怎么做**：全站 HTTPS，只给登录页加是常见的历史错误，登录后的每个请求都带着凭证。协议版本 TLS 1.2 起步、优先 TLS 1.3（握手从 2-RTT 降到 1-RTT，GeoTrust 的部署统计显示其采用率约 86%）；禁用 TLS 1.0 / 1.1 与 RC4、3DES 等弱套件；开启 HSTS 让浏览器此后强制走 HTTPS；证书续期走 ACME 自动化。CA/Browser Forum 已通过决议，证书有效期将在 2029 年 3 月前分阶段缩短到 47 天，手工续期很快会变得不可维护（来源：SSL.com 对该决议的解读）。 ```nginx server { listen 443 ssl; http2 on; ssl_protocols TLSv1.2 TLSv1.3; add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; # HSTS 先用短 max-age（如一周）观察，稳定后再加长并考虑提交 preload 列表 } server { listen 80; return 301 https://$host$request_uri; # HTTP 全站重定向 } ``` **边界在哪**：TLS 1.3 的 0-RTT（early data）为优化握手而设计，但有重放风险，开启前确认网关对非幂等接口做了防重放（见技巧 2）。HTTPS 只保护传输通道，数据落进数据库、日志、缓存之后的泄露它管不到，那是数据加密（技巧 14）的领域。证书到期监控要独立于自动化存在，自动化失灵时有告警兜底。 ### 2. 接口签名与防重放 **防什么**：HTTPS 防第三方窃听，防不了持有合法通道的人：token 被抓包后原样重发，参数被代理或中间人篡改后重发。无登录态的开放 API（靠 appKey / secret 通信）对这类攻击没有其他防线，完全依赖签名机制。业界通行方案是三件套（来源：阿里云开发者社区等一线实践，窗口取值 1~5 min）： 1. **timestamp**：请求带时间戳，服务端拒绝与当前时间偏差超过窗口（一般 5 min）的请求，压缩重放可用期； 2. **nonce**：每次请求生成随机串，服务端 Redis `SETNX` 判重，TTL 与窗口一致，过期自动清理，命中即重放； 3. **sign**：业务参数与 timestamp、nonce 按约定规则排序拼接，用 HMAC-SHA256 以 appSecret 计算签名，任一参数被篡改则验签失败。 ```java public class ApiSignInterceptor implements HandlerInterceptor { private final StringRedisTemplate redis; private final Signatures signatures; // 拼串与 HMAC 封装，appKey -> secret 走配置中心 @Override public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) throws IOException { String appKey = req.getHeader("X-App-Key"); String timestamp = req.getHeader("X-Timestamp"); String nonce = req.getHeader("X-Nonce"); String sign = req.getHeader("X-Sign"); if (appKey == null || timestamp == null || nonce == null || sign == null) { resp.sendError(401); return false; } // 1. 时间窗口 long skew = Math.abs(System.currentTimeMillis() - Long.parseLong(timestamp)); if (skew > Duration.ofMinutes(5).toMillis()) { resp.sendError(401); return false; } // 2. nonce 判重：SETNX 原子操作，TTL 与窗口一致 Boolean firstSeen = redis.opsForValue() .setIfAbsent("nonce:" + nonce, "1", Duration.ofMinutes(5)); if (Boolean.FALSE.equals(firstSeen)) { resp.sendError(401); // 重放请求 return false; } // 3. 验签：与服务端同规则拼串后 HMAC-SHA256，常量时间比较 String expected = signatures.compute(appKey, timestamp, nonce, req); if (!MessageDigest.isEqual( expected.getBytes(StandardCharsets.UTF_8), sign.getBytes(StandardCharsets.UTF_8))) { resp.sendError(401); return false; } return true; } } ``` **边界在哪**：nonce 与 timestamp 必须参与签名，否则可以被单独篡改；secret 不上传输链路；拼串规则（参数排序、空值处理、body 如何参与、字符编码）要写成双方共用的规范或测试向量，否则「验签对不上」的联调排查成本极高。签名只保证请求来自合法客户端且未被篡改，不保证业务不重复执行，重复执行由幂等（技巧 12）兜住。 ### 3. 加 IP 白名单 **防什么**：管理后台、内部运维接口、支付回调、OpenAPI 合作伙伴入口。这类接口的使用方固定且数量少，IP 白名单是最便宜的准入控制，能直接挡住扫描器的大面积试探，把暴露面从「公网任何人」收敛到「几个已知地址」。 **怎么做**：接入层配置优先于应用层实现，被拒请求不消耗应用资源；应用层用 HandlerInterceptor 兜底；云上部署时把名单下沉到安全组，网络层直接隔离。 ```nginx location /admin/ { allow 10.0.0.0/8; # 内网网段 allow 203.0.113.7; # 合作伙伴出口 deny all; } ``` ```java public class IpWhitelistInterceptor implements HandlerInterceptor { private final Set whitelist; @Override public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) throws IOException { if (!whitelist.contains(resolveClientIp(req))) { resp.sendError(403); return false; } return true; } } ``` **边界在哪**：最大的坑在取客户端 IP。`X-Forwarded-For` 是客户端可以任意伪造的请求头，直接取第一个值，白名单等于虚设。正确做法是从可信代理链反推：只有可信代理（SLB、自建 Nginx）追加的段才有效，Nginx 用 `real_ip` 模块（`set_real_ip_from` 声明可信代理 + `real_ip_header X-Forwarded-For`）先剥离可信代理再取值。白名单只适合入口固定的场景，直接面向 C 端用户的接口用不了它。 ### 4. 限流 **防什么**：OWASP API4:2023（资源无限制消耗）。CC 攻击、爬虫、突发流量、漏洞利用脚本（比如遍历 ID 取数）都会在短时间内制造超额请求。没有限流的接口，一次恶意并发就能打满连接池、线程池和数据库，安全问题在这里与稳定性问题重叠。 **怎么做**：按部署位置分四层，越靠前成本越低：接入层 Nginx `limit_req`、网关层（Spring Cloud Gateway 的 RequestRateLimiter，内置 Redis 令牌桶）、应用内（Resilience4j / Guava RateLimiter）、跨实例的分布式限流（Redis + Lua）。算法按流量形态选： | 算法 | 行为 | 适用场景 | 注意点 | |------|------|---------|--------| | 固定窗口 | 每个时间窗内最多 N 个 | 粗粒度配额 | 窗口交界处可能瞬时放行 2N | | 滑动窗口 | 任意滚动窗口内最多 N 个 | 精确计数 | Redis ZSet 实现，注意内存与清理 | | 令牌桶 | 平均速率 + 允许突发 | 削峰，容忍短突刺 | 主流网关的默认选型 | | 漏桶 | 恒定速率整流 | 保护处理能力弱的下游 | 引入排队延迟 | 分布式滑动窗口的 Lua 实现，计数与清理必须原子执行，否则并发下计数失真： ```lua -- KEYS[1]=限流键 ARGV: 当前时间ms, 窗口ms, 上限, 本次请求唯一值 local key = KEYS[1] local now = tonumber(ARGV[1]) local window = tonumber(ARGV[2]) local limit = tonumber(ARGV[3]) redis.call('ZREMRANGEBYSCORE', key, 0, now - window) -- 清理窗口外记录 if tonumber(redis.call('ZCARD', key)) < limit then redis.call('ZADD', key, now, ARGV[4]) redis.call('PEXPIRE', key, window) return 1 end return 0 ``` 限流维度按接口敏感度组合：入口按 IP 粗筛，业务接口按 userId 精确限，配合设备指纹维度。被限流时返回 429 加 Retry-After 头，客户端实现指数退避重试。 **边界在哪**：阈值来自压测数据，不是拍脑袋。纯 IP 维度在移动网络 NAT 出口会误伤真实用户（一个出口 IP 背后可能是成百上千人）；全局阈值不分层时，一个失控的定时任务能把业务请求全部挤掉。限流命中数本身要进监控，突增即是攻击或故障信号。 ### 5. 加验证码 **防什么**：自动化滥用：撞库（用泄露的账号密码批量试登录）、短信轰炸、恶意注册、刷票刷券。这类流量的特征是高频加机器行为，验证码的作用是把攻击成本从「写个脚本」抬高到「过人机挑战」，属于成本对抗而非绝对阻断。 **怎么做**：按风险触发，不要所有接口都上。登录连续失败 N 次后要求图形或滑块验证码；短信验证码必须同时有发送频控、有效期、一次性销毁、错误次数上限四件事。以短信验证码为例： ```java public void sendSmsCode(String phone) { // 60s 发送间隔，SETNX 原子判重 Boolean allowed = redis.opsForValue() .setIfAbsent("sms:rate:" + phone, "1", Duration.ofSeconds(60)); if (Boolean.FALSE.equals(allowed)) { throw new BizException(ErrorCode.SMS_TOO_FREQUENT); } String code = String.format("%06d", secureRandom.nextInt(1_000_000)); redis.opsForValue().set("sms:code:" + phone, code, Duration.ofMinutes(5)); smsClient.send(phone, code); } public boolean verifySmsCode(String phone, String input) { String saved = redis.opsForValue().get("sms:code:" + phone); if (saved == null) { return false; } boolean match = MessageDigest.isEqual( saved.getBytes(StandardCharsets.UTF_8), input.getBytes(StandardCharsets.UTF_8)); // 常量时间比较，防时序侧信道 if (match) { redis.delete("sms:code:" + phone); // 一次性：成功即销毁 return true; } // 连错 5 次作废验证码。6 位数字共 100 万种组合， // 每个码最多给 5 次尝试，穷举命中率被压到 0.0005% 量级 if (redis.opsForValue().increment("sms:try:" + phone) >= 5) { redis.delete("sms:code:" + phone); } return false; } ``` **边界在哪**：打码平台和接码平台都能绕过验证码，它只是拉高成本；验证码服务自身要限流，否则它自己就是被刷对象（短信轰炸事故里最常见的就是验证码发送接口被并发调用）。行为验证码（滑块）依赖第三方 SDK，接入前评估其故障对登录主链路的影响，准备降级开关。 ### 6. 做权限控制 **防什么**：OWASP API Top 10 的第一名。登录态校验通过，但没有校验「这个对象是不是你的」，改请求里的 ID 就能横向读取他人数据，即 BOLA（API1:2023）；普通用户直接调用管理员接口，即功能级越权（API5:2023）。这类漏洞在攻击统计中占比约 40%（来源：Salt Security），因为利用成本极低而普遍存在。 **怎么做**：把认证和鉴权分开。认证回答「你是谁」（JWT、Session，本站《Token 存储与 JWT 设计》有专门讨论），鉴权回答「你能不能动它」。鉴权分两层，两层都要做： ```java // 功能级：RBAC，能否调用这个接口 @PreAuthorize("hasRole('ADMIN')") @DeleteMapping("/admin/users/{id}") public Result disableUser(@PathVariable Long id) { ... } ``` ```java // 对象级：这条数据归不归你。归属条件进 WHERE，而不是查出来再比对 public Order getMyOrder(Long orderId, Long currentUserId) { // SELECT * FROM orders WHERE id = #{orderId} AND user_id = #{userId} return orderMapper.selectByIdAndUserId(orderId, currentUserId); } ``` 对象级校验的正确姿势是把 `userId` 放进查询条件：从数据层杜绝取错对象，也避免「查出实体再 if 比对」在缓存、并发场景下漏判。聚合接口（订单详情带收货地址）要对每个关联对象分别校验归属。 **边界在哪**：前端隐藏菜单、禁用按钮只是体验，不是安全，接口本身必须独立鉴权。网关统一鉴权后，内网服务间调用形成信任边界外的「裸奔区」，要明确哪些内部接口允许被谁调用。UUID 当对象 ID 能抬高遍历成本，但它是概率性缓解，不能替代归属校验。 ### 7. 参数校验 **防什么**：来自客户端的一切输入都不可信。不校验的后果分两类：安全类，SQL 注入的入口几乎都是未校验的参数；稳定性类，`pageSize=100000` 触发全表扫描，负数金额让下单接口算出负总价。前端校验只优化体验，服务端校验是唯一的安全边界。 **怎么做**：Spring Boot 引入 `spring-boot-starter-validation`，DTO 上挂约束注解，Controller 参数加 `@Valid`。枚举、排序方向、排序字段这类取值可穷举的参数，用白名单正则约束而不是黑名单过滤： ```java public record PageQuery( @Min(1) @Max(100) Integer pageSize, // 分页上限，防止全表拖取 @NotBlank @Size(max = 32) String keyword, @Pattern(regexp = "created_at|amount") String orderBy, // 排序字段白名单 @Pattern(regexp = "asc|desc") String orderDir) { } @PostMapping("/api/orders/search") public Result> search(@Valid @RequestBody PageQuery query) { return Result.ok(orderService.search(query)); } ``` 跨字段规则（开始时间早于结束时间）写自定义校验器，或在服务层显式校验并抛业务异常。 **边界在哪**：Bean Validation 靠 AOP 代理生效，Service 内部自调用时注解不生效，和 @Async 的自调用失效是同一个机制问题，入口层校验不能依赖「Service 上也加了注解」获得安全感。白名单优于黑名单：黑名单永远枚举不完绕过姿势（大小写、编码、注释符）。校验失败的错误信息不要回显原始输入，防止反射型 XSS。 ### 8. 文件上传校验 **防什么**：WebShell 落盘后被解析执行、恶意文件借站点分发、压缩包炸弹打满磁盘、路径穿越写到任意目录。 **怎么做**：扩展名与 Content-Type 都是客户端可伪造的声明，不能作为信任依据。校验顺序：白名单扩展名、文件头 magic number（Apache Tika 可做类型探测）、大小上限；落盘重命名，不带用户原始文件名，防路径穿越；存储与 Web 根隔离或走对象存储加独立域名，即使存进 WebShell 也无法被解析执行；图片类服务端重编码一次，可剥掉大多数注入载荷；解压类功能限制解压后总大小与条目数，防 zip bomb。 **边界在哪**：所有校验必须在服务端做，前端限制只是体验；对象存储的公开读权限按最小化配置；用户间共享文件的场景按需接病毒扫描（如 ClamAV）。 ### 9. 做转义 **防什么**：注入载荷的落地环节。存储型 XSS：昵称里夹带 `