微服务代码结构怎么设计才不踩坑

做后台开发这几年，见过太多项目因为微服务拆得乱七八糟，最后连自己人都看不懂代码往哪改。上周同事接手一个订单服务，光找支付回调逻辑就花了两天，文件夹套文件夹，命名还全是Service1、HandlerA这种，简直是代码迷宫。

别把单体架构搬进微服务

很多人以为把老系统打成几个jar包就是微服务了，其实换汤不换药。真正的微服务得按业务边界来切。比如电商系统里，用户、订单、库存各成一块，彼此通过API通信。每个服务有自己的数据库，别再共用一张user表了，否则改个字段全队提心吊胆。

标准目录结构要立住规矩

新拉一个服务，建议从这骨架开始：

order-service/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/order/
│   │   │       ├── controller/     // 接口层
│   │   │       ├── service/      // 业务逻辑
│   │   │       ├── repository/   // 数据访问
│   │   │       ├── dto/          // 数据传输对象
│   │   │       └── OrderApplication.java
│   └── resources/
│       ├── application.yml
│       └── bootstrap.yml
└── pom.xml

controller只负责接请求转参数，别写复杂逻辑；service层处理核心流程，比如创建订单前扣库存、发消息；repository专注和数据库打交道。三层各司其职，查问题时直接定位到对应目录。

接口定义提前说清楚

团队协作最怕改接口不通知。建议用OpenAPI（以前叫Swagger）把接口文档写明白。比如订单状态变更的POST请求长什么样，返回码有哪些，都标清楚。前端拿着文档就能联调，不用反复问“这个字段到底有没有”。

异常处理统一出口

见过有人在controller里直接throw new Exception("出错了")，结果日志里全是英文堆栈，运维排查时一头雾水。应该建个全局异常处理器，把业务错误包装成标准格式：

{
  "code": 1001,
  "message": "库存不足，无法下单",
  "timestamp": 1728456789
}

这样前端也好处理，弹提示框直接读message字段就行。

配置文件别硬编码

测试环境连的是test-order-db，上线发现写死在代码里连的却是prod-db，这种事故我亲眼见过。所有连接地址、超时时间、开关功能都放配置中心，比如Nacos或Apollo。本地调试时用application-local.yml，上生产自动切换profile。

微服务不是炫技，是为了解决实际问题。结构清晰了，加个新功能不再提心吊胆，半夜报警也能快速定位是哪个服务崩了。与其花时间救火，不如先把代码架子搭明白。