开发指南后端应用开发
微服务后端开发
按业务边界拆分独立后端服务，设计契约、部署、鉴权、观测和发布验证。
微服务后端由多个可以独立构建、部署和验证的服务组成。拆分的依据应是业务能力、数据所有权和团队责任，而不是把每个接口或每张表都拆成一个服务。
微服务仍然属于通用后端应用开发。它可以部署为多个 Hosted Service，但不是百积木运行时模块，也不会因为拆成多个服务就自动进入 Bundle。
什么时候选择微服务
适合以下情况：
- 不同业务能力需要独立扩缩容或独立发布。
- 服务之间有清晰的领域边界和责任团队。
- 某个能力需要与主应用隔离故障、依赖或合规配置。
- 已经具备服务级日志、指标、鉴权、契约测试和发布能力。
如果团队还无法维护独立的构建、配置、部署、回滚和排障链路，优先使用边界清晰的单体后端。微服务增加的是运行和协作复杂度，不是目录拆分技巧。
服务边界
每个服务在开发前应明确：
| 边界 | 必须回答的问题 |
|---|---|
| 业务职责 | 这个服务拥有哪项业务能力，哪些规则不属于它？ |
| 数据所有权 | 哪个服务负责写入数据，其他服务通过什么契约读取？ |
| 调用契约 | 请求、响应、错误、超时和重试语义是什么？ |
| 身份与权限 | 调用方身份、服务凭据和最终业务用户身份如何区分？ |
| 运行配置 | 数据库、密钥、Endpoint 和环境差异配置由谁管理？ |
| 观测 | 如何用 trace、结构化日志和业务指标定位一次跨服务请求？ |
禁止多个服务无边界地共同写同一组业务表，也不要把环境地址、工作区、用户或业务目录项写死在服务代码中。
推荐开发流程
- 先定义服务职责和对外契约，再确定服务拆分。
- 为每个服务建立独立的测试、构建和 Artifact 身份。
- 使用环境配置管理数据库、凭据、Endpoint 和超时参数。
- 先验证单服务健康、鉴权、数据一致性和错误模型，再验证跨服务调用。
- 使用契约测试覆盖调用方与被调用方，使用集成测试覆盖真实部署后的网络边界。
- 按服务逐步发布，记录 Artifact、Deployment、配置修订和验证结果。
- 发布失败时回滚到已验证的 Artifact，并检查调用方兼容性和数据迁移状态。
与百积木平台的关系
通用微服务可以被网站、智能体、工作流、平台应用或运行时模块调用。平台应用前端不能直接访问内部微服务地址，应通过受控的后端 Endpoint 或 App Gateway 暴露必要能力。
如果服务需要成为可安装、可配置、可通过 Runtime 方法调用的能力，应进一步评估运行时模块开发。模块定义、平台应用版本和 Bundle 版本仍然遵循各自的不可变发布边界，不能用微服务部署记录代替模块或 Bundle 版本。