# FIXME: 可能这类BP，用 3SQ 来梳理更合理？
- topic: 《从API开发生命周期到API最佳实践Checklist》 # [API-Security-Checklist/README-zh.md at master · shieldfy/API-Security-Checklist](https://github.com/shieldfy/API-Security-Checklist/blob/master/README-zh.md)
isX: true
hasPic: true
why:
- "***在实际开发中，在设计环节需要思考【拆API】怎么判断API是否应该拆分？有哪些评估因素？默认拆分还是合并？***" # 1、【回查API】2、【大力使用参数化设计】这是减少同类API数量的利器 3、【业务动作API + BFF聚合层】4、【监控驱动优化】上线后密切监控API调用量、性能、错误率。高频或问题多的API是拆分的候选者；过于冷门且简单的API可考虑合并。
- 【为啥需要这个API？】能否不写？【回查API】里能查到吗？做好【回查API】如果你需要详情数据，自己去调用。 # [后端如何减少工作量和甩锅_哔哩哔哩_bilibili](https://www.bilibili.com/video/BV1cT421i7Pz/) # 1、直接返回数据，我们BE不要拼接数据。2、【透传】让FE自己拼接好，我们直接传就可以了。更灵活（前端修改，那我们也得改，所以...）
# FIXME:
- 【是否需要拆API？】默认倾向于拆分 -> why? # 【2025-06-12】在实际开发中，在设计环节需要思考【拆API】怎么判断API是否应该拆分？有哪些评估因素？默认拆分还是合并？1、【回查API】2、【大力使用参数化设计】这是减少同类API数量的利器 3、【业务动作API + BFF聚合层】4、【监控驱动优化】上线后密切监控API调用量、性能、错误率。高频或问题多的API是拆分的候选者；过于冷门且简单的API可考虑合并。
what: # “what”里的内容（如API请求过滤、响应格式、错误码设计）应该留在“what”里，因为它们是API设计阶段的规格说明，定义了API的功能和结构，而不是具体的实现细节。“hti”（如何实现）则更关注编码、测试和部署等实际操作。例如，API响应格式的6个参数是设计时的规格，而如何在代码中实现这些格式属于“hti”。
# FIXME: 【2025-07-15】自己研究一下怎么在golang里实现完整的“参数化设计”，也就是 filter, fields, sort, ... 整套
- "***【API请求filter】【参数化设计】1、过滤/排序参数规范（如 `?filter=name:eq:test&sort=-created_at`）1、批量操作支持（批量删除/更新）***"
- 【API响应格式 6个参数】为啥这6个参数（code, data, msg, requestId, success, ts）都需要？ # [聊聊接口的返回数据结构 | 希仁之拥的博客](https://blog.keepchen.com/a/talk-about-api-response-structure.html)
- 【API响应filter】字段选择支持（`?fields=id,name`） # 我举个例子，比如说FE说需要5个参数，我是应该直接默认只返回这些数据，还是全部返回（只omit敏感数据）让FE自己获取呢？哪种更好，通常来说
# FIXME: 错误码设计，自己实践一下
# [浅谈API错误码设计 - 知乎](https://zhuanlan.zhihu.com/p/14972811454)
# [云API错误码的设计规则腾讯云云API错误码分为两级。以点号分隔。 第一级错误码统一由API平台提供 ，业务选择合适的错 - 掘金](https://juejin.cn/post/7329514858664919103)
# [如何设计API返回码（错误码）？ - Ken的杂谈](https://ken.io/note/api-errorcode-or-resultcode-desgin)
# [聊聊接口的返回数据结构 | 希仁之拥的博客](https://blog.keepchen.com/a/talk-about-api-response-structure.html)
- 【错误码设计】
- 【防重放】nonce/timestamps/sign 随机串防重，服务器验证流程？如果不同时使用这三个参数，各自都有什么问题？
- 【JWT】 # [实践出真知，聊聊 HTTP 鉴权那些事 | 董泽润的技术笔记](https://mytechshares.com/2022/04/06/something-about-http-auth/#2-HMAC) “JWT TOKEN 能防篡改但是不能防重放攻击，所以 exp 要短，同时要有 token 黑名单，还得有限流，哪怕是一小时也能把服务打爆”
htu:
- 【API文档】
- 【架构图】
hti:
hto:
- 【Mock】BE和FE中确实需要有一个主导者，但是无论谁主导都需要通过API文档做mock，来提供一个基础共识，之后才能基于这个API设计进行讨论。而非某一方主导，则另一方必须要全盘接受。API设计需要不断探索和磨合，而不是由哪一方就直接定了的。
- 【防抓包】防抓包的有效性需要分层理解：实际上大部分抓包软件是能够抓这些HTTPS包的，只是修改不了而已。即使使用私有协议也只是成本增加了，使用wireshark仍然可以看到网络包。两者均无法实现绝对防抓包，只能通过增加攻击成本降低风险。
# - 抓包和防抓包有啥区别？分别怎么实现需求？
# - 怎么防止接口被抓包？有哪些方法？ # SSL-PINNING, HPKP, HSTS, Except-CT
# - HPKP 的原理？HPKP 怎么实现防抓包？为啥不建议使用HPKP呢，有哪些问题？ # HPKP 可以避免浏览器访问到伪造证书的 HTTPS 网站；在浏览器访问 HTTPS 网站时，网站会锁定浏览器所有接收的该网站的公钥列表，只有浏览器接受的证书与之前通过 HPKP 的 header 里申明的一致时才能访问该网站。使用抓包软件代理 ssl，必然会导致私钥和原服务器的不同，公钥也不同，验证公钥就可以判断是否被抓包；采用 HPKP 验证只需要把公钥硬编码到 APP 就可以了。
#
# - 怎么绕过 SSL-PINNING？ # 可以通过`justTrustMe`这个 Xposed 模块，来禁止 SSL 证书验证
# - SSL-PINNING 有哪些问题？ # SSL-PINNING 证书到期后会导致 APP 拒绝服务；更好的方法是走默认的操作系统 CA 验证，而不是 app 自己实现 CA 验证，因为 app 不能对证书信息进行实时更新，可能会出现很严重的问题
#
# - "*为什么你抓不到 baidu 的数据？（app 能获取数据，但是抓包软件抓不到数据，为什么？）*" # [为什么你抓不到baidu的数据](https://mp.weixin.qq.com/s?__biz=MzUzNTY5MzU2MA==&mid=2247497288&idx=1&sn=1d634021528643c2f71e7cbf4dd7a0f7) 因为 charles 之类的抓包软件只抓 ws 和 http，搞一个私有协议就绕过了。所以，用 lua 写一个 wireshark 的解析私有协议的插件，就能抓到了。因为大部分 app 都不会去搞私有协议这些的，所有抓包软件默认不抓这些协议。具体操作：pre_master_key(, client random, server random) 用tcpdump把加密的key导出（ssl.key），再给wireshark配置好这个ssl.key就可以抓取数据了
- 【API优化】 # [这 11 条接口性能优化技巧，利好每日睡眠](https://mp.weixin.qq.com/s?__biz=MzUzNTY5MzU2MA==&mid=2247495605&idx=1&sn=4d4d4f04a1df44a92d1e1ad046b6a3fb)
# FIXME: 这个也需要加进去
- 【架构方面】
#- 第三方集成：
# - API 网关配置（路由/限流/熔断）
# - 监控告警（Prometheus/Grafana）
# - 日志聚合（ELK/Sentry）
# - 消息队列集成（异步任务）
#- 依赖管理：
# - 第三方 API 封装（支付/短信）
# - 服务降级策略（熔断阈值设置）
record:
- date: 2025-04-19
des: 【用DrawIO画整个流程，得到3DSTD2M()】Design-Develop-Doc-Secure-Test-Deploy-Monitor-Modify，其中比较重要的就是，Design, Doc, Secure 这三步。这个图在此之前画过两个版本，依次是 “发传收验”、Req-Resp 这两个。但是都不太满意。网上搜了一下 API lifecycle 最终确定了这个图。从API开发生命周期入手是更好的选择。
- date: 2025-07-27
des: 【精简“架构设计流程”到4步：3DO(设计-开测-部署-优化)】在整理“API设计”的why时意识到，架构设计本身就是API设计的前置操作。所以“API设计”的why应该是
- date: 2025-08-05
des: 【把“架构设计流程”整合到3w3h框架】之前整理过之后，相较之前已经清晰很多了，但还是记不住。所以就尝试整合到3w3h里，但是这里需要注意的是，3w3h通常用于使用，但是这里则用于“实现API”。
从API开发生命周期到API最佳实践Checklist
8 min read