微服务下电商用户平台的 API 设计与解耦实战：开源商城架构拆解

一、API 设计：跟着业务拆，按领域建规范

1. 四大业务域：把 API 边界划清楚

• 身份域：管 “登录注册” 的核心
  只负责用户身份认证，接口就三个核心：注册（/api/v1/identity/register）、登录（/api/v1/identity/login）、注销（/api/v1/identity/logout）。登录接口的响应特别 “纯粹”，只给 userId、token 和过期时间，比如：
  json

   

  \{ "code": 200, "message": "success", "data": \{ "userId": "10001", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expireTime": "2024-08-28T12:00:00Z" \} \}

   
  
  
  后来要加 “短信验证码登录”，只在身份域里加了/api/v1/identity/login-by-sms，其他域的代码一行没改，半天就上线
• 权限域：控制 “谁能做什么”
  用 RBAC 模型（角色权限）设计，权限细到按钮级，比如 “商品编辑”“订单查看” 是两个独立权限。接口包括查角色（/api/v1/permission/roles）、验权限（/api/v1/permission/check），运营要给客服开 “仅查看订单” 的权限，直接调接口配角色就行，不用改系统代码。
• 档案域：管 “用户的个人信息”
  处理昵称、手机号、收货地址这些数据，接口像/api/v1/profile/get（查信息）、/api/v1/profile/addresses（管地址）。这里最关键的是敏感信息保护 —— 手机号返回时自动变成138****5678，身份证号只显首尾几位，合规《个人信息保护法》时，只改脱敏规则就够了。
• 关系域：支撑 “社交电商” 场景
  针对用户关注、粉丝列表这些功能，接口如/api/v1/relation/follow（关注用户）、/api/v1/relation/fans（查粉丝）。有客户要做 “好友拼单”，直接基于关系域 API 扩展，不用动身份、权限这些核心模块，两周就上线了。

2. 接口规范：定死 “规矩”，避免混乱

• 版本控制：老接口不崩，新功能照加
  所有 API 的 URL 都带版本号，比如/api/v1/，大改接口（如改字段名）就升v2，小改（如加可选参数）就升v1.1。之前给注册接口加 “邀请码” 字段，用/api/v1.1/identity/register，老用户用的v1接口没受影响，过渡期很稳。
• 命名和操作：看 URL 就知道要干嘛
  资源用名词复数，比如 “地址” 是/addresses不是/address；操作靠 HTTP 方法区分 —— 查用 GET、创建用 POST、全量改⽤ PUT、删⽤ DELETE。比如查地址列表是GET /api/v1/profile/addresses，改地址是PUT /api/v1/profile/addresses/123，新人接手不用查文档也能懂。
• 参数校验：错了直接说清楚
  用规则校验请求参数，比如手机号必须是1[3-9]\\d\{9\}，用户名要 2-20 字符。校验失败就返回明确的错误，比如：
  json

   

  \{ "code": 400, "message": "参数校验失败", "errors": [ \{"field": "phone", "message": "手机号格式不正确"\} ] \}

   
  
  
  前端开发不用猜错在哪，后端也少了很多 “参数不对” 的排查工作
• 分页排序：所有列表接口都一样
  查列表的接口统一支持pageNum（页码）、pageSize（条数）、sort（排序字段）、order（方向），响应里带分页信息：
  json

   

  \{ "data": \{ "items": [...], "pagination": \{ "pageNum": 1, "pageSize": 10, "total": 120, "pages": 12 \} \} \} 前端不用为每个列表写不同的分页逻辑，直接复用组件就行。

   
• 幂等设计：重复点也不怕错
  写操作（如创建地址）必须传requestId（唯一 ID），就算用户手抖点了两次，系统也知道是同一个请求，只会执行一次。之前有用户在 APP 上重复点 “添加地址”，因为requestId相同，没出现两条一样的地址。

二、服务解耦：别绑在一起，各活各的

1. 通信解耦：该同步同步，该异步异步

• 同步调用：只在 “必须实时要结果” 时用
  比如订单服务创建订单前，得确认用户身份有效，这时候用同步调用 —— 订单服务调用户平台的/api/v1/identity/check接口。但同步有风险，万一用户平台慢了，订单服务会跟着卡，所以加了 1 秒超时和熔断：调用失败就返回 “匿名用户”，先让订单创建成功，后续再补身份校验。
  之前有次用户平台临时故障，订单服务触发熔断，用户照样能下单，只是个人中心显示 “未完善信息”，没影响核心交易。
• 异步事件：状态变了，发个通知就行
  用户注册、改手机号、账户冻结这些状态变化，用户平台不主动调用其他服务，而是发个 “事件” 到 Kafka，谁需要谁就自己听。比如用户注册成功，发一个USER_REGISTERED事件：
  json

  \{ "eventType": "USER_REGISTERED", "timestamp": 1693190400000, "userId": "10001", "data": \{ "registerTime": "2024-08-28T08:00:00Z", "registerChannel": "APP" \} \}

   
  
  
  营销服务听了这个事件，给新用户发优惠券；消息服务听了，发欢迎短信；订单服务不需要，就不用管。后来加积分服务，只让它订阅这个事件，给新用户加积分，完全不用改用户平台的代码。

2. 数据解耦：我的数据我管，别来直连库

• 数据存得 “隔离”
  用户的账户、密码、权限数据存在专属 MySQL 库，按 userId 哈希分表，支撑千万级用户。密码这种敏感数据，单独存在加密表里，和基础信息表物理分开，就算基础表被访问，密码也不会泄露。
• 缓存自己维护，更新及时同步
  用户昵称、头像这些高频访问的数据，存在 Redis 里（键是user:base:\{userId\}），过期时间 2 小时。如果用户改了昵称，档案服务发USER_INFO_UPDATED事件，缓存服务听了就删旧缓存，下次查就从数据库读新数据，避免缓存脏读。
• 下游服务可 “存副本”
  订单服务要显示用户昵称和手机号，不用每次查订单都调用户平台 API—— 订单服务自己存一份，然后听USER_INFO_UPDATED事件，用户信息变了就同步更新。这样既减少了跨服务调用，订单详情页加载速度也快了不少。

3. 部署解耦：各自扩容，故障不扩散

• 容器化部署，自动扩缩容
  身份、权限、档案服务分别打包成 Docker 镜像，跑在 Kubernetes 上。大促前用户集中登录，身份服务的 CPU 超 70%，Kubernetes 自动加实例；流量降下来后再自动减，不用人工盯着。有个电商 “黑五” 大促，登录请求涨 10 倍，身份服务从 3 个实例扩到 15 个，响应时间一直稳在 200ms 内。
• 服务网格控流量，灰度发布安全
  用 Istio 做服务网格，新功能上线时，先把 10% 流量导到新版本 API，没问题再慢慢加到 100%。还能设熔断：身份服务连续 50 次报错，就暂时切断流量，不让故障传到订单、支付服务。之前身份服务新版本有 bug，只影响 10% 用户，很快就回滚了。
• 独立监控告警，问题精准找
  用户平台有专属监控面板，盯注册转化率、登录成功率、API 响应时间，告警只通知负责的运维团队。比如登录接口 P95 响应超 500ms，只给用户平台运维发告警，不用打扰订单团队，问题定位快多了。

三、安全防护：开放 API 也要守住边界

1. 认证授权：确认 “你是谁，能做什么”

• JWT 令牌：无状态认证，不用存会话
  用户登录后生成 JWT 令牌，里面带 userId、角色、过期时间，用密钥签名。后续请求只要在 Header 里带Authorization: Bearer \{token\}，网关就验有效性，不用每次查数据库。密钥定期换，就算泄露，影响也有限。
• 网关层先拦 “无权请求”
  网关先验令牌，再查用户有没有权限访问接口 —— 普通用户不能调/api/v1/admin/*接口，没权限直接返回 403，不用传到后端服务，减少压力。
• 支持第三方登录，用户不用注册新号
  对接微信、支付宝登录，按 OAuth 2.0 协议走：用户平台发授权码，第三方拿码换令牌，再用令牌查用户昵称、头像（得用户授权），拿不到敏感信息。有个电商加了微信登录后，新用户注册率提了 30%。

2. 数据安全：传输加密，敏感信息藏好

• 全程 TLS 加密，数据不被窃听
  所有 API 通信都用 TLS 1.3 加密，登录传密码、查银行卡信息时，数据在网路上是加密的，中间人截不到。敏感接口还加 API 密钥签名，签名里带时间戳和随机数，防止别人截请求反复调用。
• 敏感信息自动脱敏，合规不踩坑
  响应里的手机号显示138****5678，身份证号显示110********1234，脱敏规则能通过配置改 —— 要符合欧盟 GDPR 就调细粒度，要符合国内法规就按国内要求来，不用改代码。
• 双层限流，防恶意攻击
  按用户 ID 和 IP 限流：普通用户登录 10 次 / 分钟，注册 5 次 / 小时；同一 IP1 分钟内刷 50 次登录，就封 1 小时。之前有黑客用脚本刷注册，没到 1 小时就被封了，没造成垃圾账号泛滥。

3. 审计追溯：操作留痕，出问题能查

• 操作日志存 180 天，谁干的都清楚
  所有 API 调用都记日志：userId、IP、请求参数摘要、响应状态，存 180 天以上。改密码、加权限这些敏感操作，还记前后对比，比如 “密码从123 改成456”，审计时一查就明。
• 异常监控抓风险，提前防攻击
  实时盯异常率：认证失败、权限不足的次数超 1% 就告警。还能分析异常模式 —— 同一 IP 试 10 个账号登录，可能是暴力破解；同一用户在两地登录，可能是账号被盗，运维能及时介入。

四、实战效果：解耦带来的真实改变

• 开发快了：用户平台和订单、营销系统并行开发，加 “第三方登录” 从 2 周缩到 3 天；
• 抗流强了：大促登录请求涨 10 倍，自动扩缩容扛住，响应时间稳在 200ms 内；
• 故障小了：一次档案服务 bug 只影响个人中心，订单支付没受影响，恢复时间短 60%；
• 转化高了：集成社交登录后，新用户注册转化率提 35%。

未来：解耦和安全要持续做

• API 网关更智能：用 AI 分析流量，自动识别脚本攻击，动态调限流规则；
• 事件驱动更成熟：用 Knative Eventing 跨集群传事件，用户平台和积分服务不在一个集群也能通信；
• 零信任落地：就算内部服务调用，也要验身份和权限，不默认信任任何调用方。