上线前一天晚上11点测试环境突然全挂。我盯着满屏的红色报错手心冒汗。第二天上午就要给客户演示结果测试环境调接口全超时回调一个都收不到。排查了两个小时才发现是同事改了配置没同步测试环境用的还是过期的AppSecret。那晚我熬到凌晨3点才把环境修好第二天顶着黑眼圈做演示居然过了。但从那以后我立了个规矩——任何微信API项目必须按流程走5个阶段一个都不能少。今天把这个流程整理出来给同样在做个微API的朋友参考。一、环境搭建四套环境必须隔离这是最基础也最容易被忽略的一步。很多人图省事开发测试都挤在一个环境里结果改着改着就分不清哪份代码是哪份了。做什么搭开发、测试、预发、生产四套环境配置完全隔离。怎么做开发环境本地或者开发服务器用Mock数据不连真实微信测试环境用测试号连真实Eyun API但权限受限预发环境和生产配置一模一样只是不对外生产环境正式号正式配置常见坑四套环境的AppSecret搞混。我们团队现在用.env文件管理每个环境一个文件部署时自动加载再也没串过。二、单元测试不依赖真实微信很多人觉得微信API项目没法做单元测试接口都是调别人的测啥。错越是依赖外部服务越要做单元测试。做什么把微信API调用全部Mock掉只测自己的业务逻辑。怎么做用mock库把Eyun的SDK调用替换成假返回专注测试业务分支——成功、失败、超时、异常返回各种情况都要覆盖。常见坑单元测试连了真实微信。一跑测试就发真消息号被封了都不知道咋回事。记住单元测试永远不碰真实API。三、集成测试用测试号真实调单元测试Mock了所有外部依赖但Mock终究是假的真实API的行为必须用集成测试验证。做什么用测试号真实调用Eyun API跑完整业务流程。怎么做准备1-2个测试号写端到端的测试用例——发消息、收回调、处理事件、更新状态整个链路走一遍。每次提测前必跑。常见坑测试号用久了风控变高。我们有个测试号用了大半年突然一天所有接口都报风控排查半天才发现是号本身的问题。建议测试号定期轮换别一个号用到天荒地老。四、灰度发布先10%再全量这是我最重视的一个环节。直接全量上线出了问题就是全量故障没法收场。做什么先放10%流量到新版本观察1天没问题再逐步放量。怎么做用网关层做流量路由按用户ID取模分流。10%跑一天看监控各项指标正常再放到30%、50%最后100%。常见坑灰度时间太短。有次我灰度跑了2小时就看指标正常直接全量结果到晚上高峰期新版本扛不住回调堆积了几万条。灰度至少跑满一个业务周期覆盖高峰低谷。五、全量上线分批切换可回滚灰度验证没问题最后一步全量上线但全量不等于一把梭。做什么分批切换流量到新版本随时保留回滚能力。怎么做按批次切换——先切一半观察30分钟没问题再切另一半。新旧版本并行运行一旦新版本异常立马把流量切回老版本。常见坑没有回滚预案。新版本上线发现数据库字段不兼容想回滚发现老版本已经被删了。永远保留上一个稳定版本回滚开关提前测好。五阶段上线Checklist阶段关键动作完成标志环境搭建四套环境配置隔离各环境配置独立可切换单元测试Mock外部API测业务逻辑覆盖率80%不连真实微信集成测试测试号端到端跑全流程所有用例通过回调正常灰度发布10%流量观察1天监控指标无异常全量上线分批切换可回滚全量稳定运行24小时灰度发布的流量路由逻辑灰度的核心就是路由下面这段是我们项目里用的分流逻辑按用户ID取模简单可靠def route_request(user_id, gray_percent10): # 用户ID取模100落在0-99 bucket hash(user_id) % 100 # 落在0到gray_percent-1的走新版本 if bucket gray_percent: return v2 # 其余走老版本 return v1 # 灰度放量10 - 30 - 50 - 100 # 每次放量前观察监控至少4小时 gray_percent load_from_config(gray_percent) version route_request(current_user_id, gray_percent)这套逻辑的好处是同一个用户始终走同一个版本不会出现上一秒新版本下一秒老版本的割裂体验。放量只改一个配置项回滚也是。写在最后别跳过任何环节每个环节省的时间都会在后面加倍还回来。我自己就吃过亏——跳过灰度直接全量结果线上故障回滚加修复熬了一整夜比走流程多花5倍时间。从那以后5个阶段我一步都不省。微信API开发看着简单调几个接口嘛但真要做到稳定上线、长期跑着不出事靠的就是这套流程。个微API和Eyun 项目尤其如此账号资源宝贵一旦封号或者故障损失不是重写代码能补回来的。如果你正在做这块建议先把流程理顺再谈功能。流程稳了功能迭代才有底气。更多微信API开发的流程实践和踩坑记录可以参考 Eyun开发文档里面有完整的开发规范和注意事项。