一、开放平台设计
1. 开放平台概念
开放平台是将自身能力通过标准化接口提供给第三方开发者调用的技术平台。
提供多种调用方式（如SDK、API等）包含用户管理、权限控制、限流配额等配套系统，形成开发者生态而非单纯的技术接口。
2、技术实现：
基于HTTP/HTTPS协议（如高德Web服务API）
支持多种数据格式（JSON/XML）
需要申请应用Key进行鉴权
不同用户类型具有差异化访问权限
3、开发要点：
需要将企业内部系统能力标准化（如用户系统、订单系统）
重点考虑安全控制（鉴权、限流、配额）
需提供完善的开发者文档和支持体系
通常采用微服务架构实现能力开放
4、开放平台设计
1）公司内部接口
功能复用性：当公司内部开发的系统功能被验证有效后，发现其他企业也有类似需求，可以考虑将接口开放给外部使用
商业化潜力：通过API接口服务实现功能变现，外部企业支付费用即可调用接口服务
转型准备：从内部使用转向对外开放需要做好接口标准化和规范化工作
2）对外接口
接口设计原则
核心概念：RESTful是一种基于HTTP协议的设计风格，全称为Representational State Transfer（表现层状态转移）
资源导向：所有接口设计都围绕资源展开，URL应直接体现资源名称（如/user、/order）
HTTP方法映射：通过HTTP方法（GET/POST/PUT/DELETE）表达对资源的操作意图
版本控制：接口需要包含版本号（如v3），确保升级时能兼容老版本用户
5、完整API设计要素
必备组件：
协议（HTTP/HTTPS）
域名
资源路径
版本号
标准HTTP方法
设计比喻：就像招待客人前需要打扫房间，对外开放的接口需要比内部接口更规范
状态转移：通过接口改变资源状态（如用户从”未启用”变为”已启用”）
接口开放流程
6、三步调用法：
申请API密钥（Key）
拼接包含Key的请求URL
接收并解析返回数据（JSON/XML格式）
编码规范：默认使用UTF-8编码
限流机制：服务调用量存在限制，需注意查阅配额
7、API设计与管理
RESTful设计
资源定位
API设计中的资源定位
核心要素：协议、域名、路径、版本和动作（POST/PUT/PATCH/DELETE/GET）共同构成资源定位
示例说明：操作用户资源时路径应设计为/users，订单资源为/orders，保持资源名词化表达
使用名词而非动词来定位资源
设计原则：必须使用名词（如users/orders）而非动词（如add/update）作为资源标识
错误示范：传统设计中常见的/addUser、/updateUser等动词形式不符合RESTful规范
正确做法：通过HTTP方法区分操作类型，如POST表示新增，PUT表示修改
复数建议：优先使用复数名词（如users），因查询操作通常返回集合数据
HTTP动作在资源定位中的应用
动作映射：
POST：创建资源（替代add）
PUT：全量更新资源（替代update）
PATCH：局部更新资源
DELETE：删除资源
GET：查询资源
特殊方法：OPTIONS主要用于调试场景
使用名词而非动词
实现方式：所有操作语义通过HTTP方法表达，URL路径始终保持名词形式
技术实现：Spring Boot中通过@PathVariable注解获取URL中的动态参数
用层级和斜杠表示资源关系
层级表示法：使用/users/123/orders表示用户ID为123的所有订单
设计要点：保持各层级均为名词，通过路径嵌套直观展示资源从属关系
用HTTP动词
PUT与PATCH区别：
PUT需要传递资源全部字段进行完整更新
PATCH只需传递需要修改的字段
查询参数：使用问号附加查询条件，如/users?name=张三
8、状态码的设计
标准结构：
数字状态码（如200）
提示信息（说明操作结果）
数据体（对象或列表形式）
开放平台实践：主流API平台均采用类似结构返回标准化响应
响应结果的格式
服务示例与参数详解
status字段：返回结果状态值，0表示失败，1表示成功
info字段：当status为0时返回错误原因，成功时固定返回”OK”
infocode：详细状态码，10000代表正确，其他值需参考状态码表
suggestion结构：包含keywords（建议关键字列表）和cites（建议城市列表）
districts结构：下级行政区列表，包含district元素及其子级信息
keywords参数：支持行政区名称、citycode、adcode三种形式，且只支持单个关键词搜索
subdistrict参数：控制返回下级行政区的级数（0-3），分别对应不返回/返回下一级/下两级/下三级
extensions参数：控制是否返回边界坐标，base不返回，all只返回当前查询district的边界值
状态码与返回信息
状态码体系：采用三层结构设计（status+info+infocode），便于快速定位问题类型和具体原因
错误处理机制：当status为0时，info会明确提示如”INVALID_USER_KEY”等具体错误类型
成功响应示例：包含完整数据结构，如districts数组内包含各级行政区划信息
错误案例与状态码解析
典型错误：无效用户密钥会返回status=0，info=”INVALID_USER_KEY”，infocode=”10001”
调试建议：遇到错误时应先检查status和info字段，再根据infocode查阅官方文档
多条件查询设计思路
参数组合：采用URL参数形式，格式为”?条件1=值1&条件2=值2&条件3=值3”
逻辑关系：默认多个条件为AND关系，复杂逻辑需在服务端特殊处理
设计原则：保持URL简洁，避免在路径中包含过多查询条件
案例1：查询用户课程信息
优选方案：体现资源层级关系
替代方案：适合简单查询场景
设计要点：优先考虑资源归属关系，次要条件使用查询参数
案例2：用户信息增删改查
错误示范：在URL中使用动词（create/delete/show/update）
正确做法：
POST /api/accounts/ 创建新用户
DELETE /api/accounts/1 删除1号用户
GET /api/accounts/1 获取用户信息
PUT /api/accounts/1 修改用户信息
设计原则：通过HTTP方法区分操作类型，URL保持名词形式
案例3：用户间转账设计
欠佳设计：post/api/accounts/1/transfer/500/to/2（包含动词和操作细节）
推荐设计：post /api/transaction?from=1&to=2&money=500
优化要点：
使用事务性资源名词transaction
操作参数通过查询字符串传递
保持URL的简洁性和可读性
版本控制
版本控制的重要性
API升级需求：当API需要修改升级时，必须同时支持新旧版本用户，特别是开放平台场景下无法强制用户升级
商业契约约束：已付费用户必须保证服务连续性，不能单方面终止老版本服务（如”收了钱就得一直用着”）
生命周期管理：需要系统化考虑老版本如何废弃、新版本如何过渡的完整流程
9、版本控制的方法
URL中的版本控制
路径标识法：在URL路径中直接嵌入版本号（如高德地图API的/v3/config/district）
参数标识法：通过查询参数指定版本（如?version=3）
实践建议：虽然不符合严格RESTful规范（版本不属于资源），但实际广泛采用（如高德、支付宝等大厂案例）
Header中的版本控制
自定义Header：通过Version等自定义头字段传递版本信息
Accept头方案：采用Accept: application/vnd.供应商.接口.v1+json格式
结构解析：包含供应商标识（如高德）、接口名称、版本号和响应格式
优势：保持URL纯净，严格遵循RESTful资源定位原则
无版本趋势
核心思想：通过后端兼容性设计避免暴露版本概念
实现方式：
采用渐进式字段扩展（新增字段不影响老功能）
设计可扩展的数据结构
使用默认值处理缺失字段
适用场景：内部系统或可控环境下的API演进
10、兼容性设计原则
版本兼容策略
新版本兼容老版本：确保新版API能正确处理老版本请求（更易实现且常见）
老版本兼容新版本：预测未来需求难度大，通常避免采用
沟通最佳实践
术语明确化：避免使用”向前/向后兼容”等易混淆表述
示例说明：建议采用”新版本兼容老版本”等无歧义表述
团队规范：架构设计中应建立统一的术语体系（如避免使用”PD”等模糊缩写）
工程实践：在订单详情接口中通过version头字段控制版本
设计建议：选择符合团队习惯的方案，重点保持一致性而非绝对正确性
11、API文档
API文档的重要性
核心原则：遵循RESTful设计，即Representational State Transfer，核心是资源化设计，充分利用HTTP协议支持的特性
版本控制：
URL中直接体现版本号
通过Header中的version键值对控制
使用Accept头指定版本格式，如application/vnd.供应商.v1+json
新版本必须兼容老版本，避免破坏性变更
文档规范：
避免使用拼音缩写等不易理解的命名方式
必须编写完整的接口文档，否则会导致维护困难
文档应确保即使负责人离职，项目也能正常运转
API文档的可读性与完整性
可读性要求：
文档应清晰展示使用步骤，如高德地图API的”第一步申请Key，第二步拼接URL，第三步解析数据”
减少客服支持压力，用户能独立理解和使用
完整性要求：
每个参数必须详细说明含义、规则、是否必填、默认值
提供实际调用示例，如高德地图的keywords参数示例”山东”
包含错误码说明和使用限制
支持在线调试功能，如高德地图的”运行”按钮
参数说明：
polyline：行政区边界坐标点，多地块用”|”分隔
center：区域中心点坐标
level：行政区划级别（国家/省/市/区县/街道）
districts：下级行政区列表
API文档工具介绍
常用工具：
Apifox：可导出完整文档
Postman：支持接口测试和文档生成
Swagger：自动生成交互式文档
生成原理：
通过注解标记API方法和参数
程序扫描代码自动提取文档内容
示例：使用@API注解标记方法，@Param说明参数
API文档生成示例
文档结构：
接口描述：功能说明和使用场景
参数说明：每个参数的名称、类型、必填、示例
调用示例：完整的请求URL和响应示例
错误码：可能的错误代码和解决方案
最佳实践：
采用”约定大于配置”原则，统一规范
即使规范不完美，也要保持统一
文档应与代码同步更新，避免过时
11、RESTful API设计规范
核心原则：Representational State Transfer架构风格，强调通过HTTP协议原生方法（GET/POST/PUT/DELETE等）操作资源
版本控制方案：
URL路径：直接在URI中嵌入版本号（如/api/v1/resource）
Header字段：
自定义头：通过X-API-Version等字段传递
Accept头：使用供应商特定格式（如application/vnd.company.v1+json）
兼容性要求：新版本必须向下兼容旧版本，避免破坏现有客户端调用
二、灰度发布
1. 灰度发布的概念
1）新版本升级后用户反馈问题
传统部署问题：直接停用老程序部署新程序会导致服务中断，如凌晨两点停机部署
回滚困难：新版本出现bug时恢复老版本需要更长时间，造成更长的不可用期
用户体验风险：淘宝商家发布商品页面升级后部分用户投诉难用，部分用户觉得好用
2）用户使用习惯问题
习惯差异：用户对新功能的接受程度存在个体差异，无法提前预知
案例说明：淘宝技术十年书中记载的商品管理页面升级案例，证明用户反馈存在两极分化
3）灰度发布的概念
核心思想：新功能不是一次性对所有用户开放，而是逐步分阶段开放
颜色隐喻：灰色介于黑(系统关闭)和白(系统上线)之间，表示过渡状态
别称说明：金丝雀发布源于煤矿工人带金丝雀下井检测毒气的典故
测试方法：AB测试是灰度发布的变种，让不同用户群体体验不同版本功能
2. 灰度发布的原因
1）灰度发布是风险管理策略
风险控制：小范围测试可避免问题影响所有用户
数据收集：在小范围内收集用户反馈和监控数据
决策依据：为是否全面上线新版本提供评估依据
2）灰度发布的功能
降低风险：控制问题影响范围
快速反馈：优先获取核心用户意见
服务持续：新旧版本并行运行不中断
生产测试：在真实环境进行最终验证
3）实际案例：在生产环境中测试
测试方案：通过用户属性字段区分正式用户和测试用户
实施细节：测试用户使用新版本功能，正式用户仍用旧版本
优势说明：测试环境与生产环境完全一致，可发现绝对路径等潜在问题
技术自信：明确问题后技术人员应自信解决，不要过度紧张
3. 灰度发布的做法
1）识别小部分用户
属性分类标准：通过用户属性来区分小部分用户，包括：
年龄属性：如大于18岁
付费属性：如VIP和非VIP用户
活跃属性：如近期2天内登录的用户
地理属性：如经常在美国上网的用户
2）区分新老系统
区分新老系统的常见方法
基础区分方式：
IP地址区分
端口号区分
版本号区分（可通过URL、查询参数或HTTP头体现）
最佳实践：版本号放在URL中是最方便的实现方式
版本号在URL中的体现
实现方案：
URL路径体现：如/v2/api
查询参数体现：如?version=v2
HTTP头体现：需前端额外封装
注意事项：HTTP头方式需要前端配合，不如URL方式直接
自定义数据类型在注册中心的应用
实现原理：服务注册时添加metadata自定义数据
新系统注册时添加特定标识（如a）
老系统不包含此标识
优势：无需修改调用方代码，通过注册中心自动区分
3）让对应的用户找到该找的系统
分发系统架构
核心组件：
用户请求入口（如nginx/gateway）
规则引擎（读取规则表）
新旧系统实例
工作流程：
用户请求到达分发系统
解析用户属性（年龄/VIP/活跃度/地理位置）
查询规则表匹配对应系统
转发请求到指定系统
规则配置实现
规则表示例：
条件：大于18岁
动作：转发到URL A
技术实现：
nginx+lua脚本：读取数据库动态路由
gateway方案：Java代码实现规则判断
灰度切换：通过修改规则表逐步扩大新系统使用范围
数据库变更处理
安全变更原则：
优先采用新增字段/表的方式
避免直接修改或删除现有字段
必须修改时采用镜像表+数据迁移方案
灰度发布限制：当新旧系统对数据库结构有不同要求时，不适合使用灰度发布
4. 常用的发布方式
1）蓝绿发布
核心机制: 同时运行两套系统（旧版本和新版本），规格保持一致
切换过程:
流量默认全部请求老系统
升级时将所有流量切换到新系统
发现问题可立即切回老系统
优势:
部署简单（仅需切换地址）
故障恢复快（秒级回滚）
缺点:
需要双倍硬件资源
新版本故障影响范围大
适用场景:
系统不繁忙时段（如后半夜）
对稳定性要求高的关键业务
2）滚动发布
设计目的: 解决蓝绿发布资源浪费问题
实现方式:
以3节点系统为例：
先部署1个新版本节点
逐步替换剩余2个旧节点
最终全部升级为新版本
资源消耗: 仅需N+1资源（N为原节点数）
特点:
硬件成本低于蓝绿发布
升级过程呈现”滚动”特征
系统始终有服务可用（无全量切换）
3）红黑发布
混合特性: 结合蓝绿发布与灰度发布特点
工作流程:
新/旧版本同时运行
新版本先对少量用户开放
逐步扩大新版本服务范围
优势对比:
比蓝绿发布更稳妥（渐进式验证）
比灰度发布操作更简单
适用场景: 需要平衡风险与操作复杂度的场景
4）AB测试发布
本质: 多版本并行验证机制
执行过程:
同时上线多个功能版本
不同用户群体使用不同版本
收集用户反馈数据对比
决策机制: 采用”赛马机制”选择最优版本
应用价值:
降低功能迭代风险
数据驱动的发布决策
优化用户体验指标
