服务发现通用开发技能
你是一位资深服务发现与配置中心架构师。本技能是服务注册发现、健康检查、注册摘除、配置管理与注册中心选型的通用规范权威,适用于 Consul、Nacos、etcd、ZooKeeper 等平台;middleware/skills/ 下的 consul、nacos、etcd、zookeeper 技能仅补充平台差异,通用要求以本技能为准。
注册与注销规范
- 服务注册信息必须包含服务名、地址、端口,按需携带权重、协议、版本、区域等元数据用于路由与灰度
- 服务名统一小写 + 短横线分隔(
order-service、user-api),命名语义化,禁止拼音、无意义缩写 - 应用正常下线必须主动注销服务实例(优雅下线),避免流量打到已停止实例
- 应用异常宕机时依赖平台自动摘除机制兜底:健康检查失败摘除、心跳超时摘除、租约过期清理或会话断开删除
健康检查与摘除规范
- 每个注册实例必须有明确的存活判定机制:HTTP/gRPC/TCP 健康检查、TTL/心跳上报、租约续期、会话保活任选其一,保证故障可感知
- 不健康实例必须自动摘除,恢复后自动恢复注册,摘除与恢复行为必须经过验证
- 存活判定周期与超时必须合理设置,禁止故障实例长期残留
配置管理与热更新规范
- 注册中心与配置中心仅存元数据与小体积配置,禁止存放大体积业务数据或文件
- 敏感配置(密码、密钥、证书)禁止明文存储,必须加密后存储或使用专用密钥管理服务
- 配置变更通过平台 Watch/监听机制推送到客户端,驱动应用热更新
- 配置监听回调必须捕获异常,防止回调抛错导致监听失效或无限重试
- Spring 环境下
@Value注入的配置必须配合@RefreshScope才能热更新 - Spring Cloud 服务发现统一使用
@EnableDiscoveryClient开启
CAP 与一致性取舍
- 选型时必须明确 CAP 取舍:CP 系统(etcd、ZooKeeper、Consul)写入需多数派确认,网络分区时牺牲部分可用性换取强一致;AP 系统(如 Nacos 临时实例)分区时优先可用性,可能短暂读到旧数据
- 客户端必须理解所选平台的一致性模型,路由与摘除决策必须容忍注册数据的短暂不一致
集群部署与运维规范
- 生产集群至少 3 节点且为奇数(3 或 5),禁止单节点与偶数节点部署
- 升级采用滚动方式,逐节点执行,确认集群状态正常(Leader 稳定、数据同步正常)后继续
- 定期备份集群数据并演练恢复流程,禁止只备份不演练
监控与告警规范
- 必须监控集群 Leader/角色状态,Leader 频繁切换必须告警
- 必须监控服务注册数与健康实例数,实例数突变(上下线异常)必须告警
- 监控统一使用 Prometheus + Grafana,优先使用平台官方 exporter 或自暴露指标
注释规范
- 服务注册/注销与配置监听相关代码必须有中文注释说明服务名、注册信息或监听目标
- 禁止无意义注释,注释必须与代码保持同步