服务初始化
约 1102 字大约 4 分钟
2025-03-03
本教程面向已取得平台源码的开发者，说明怎样在平台内增加服务或扩展现有服务。仅开发独立业务时，从 iot-basic 应用模板开始，运行依赖使用公开 ur-kit。
1. 先确定服务边界
| 需求 | 推荐位置 | 原因 |
|---|---|---|
| 用户、组织、角色等系统能力 | Core 对应服务 | 复用既有身份、权限和基础模型 |
| 产品、设备、物模型与数据处理 | Things 对应服务 | 保持设备状态与数据链路一致 |
| 平台内部新的领域模块 | 所属模块的 service/ 或 backend/apps/ | 独立合同、持久层和启动生命周期 |
| 企业自己的业务系统 | 独立仓 + ur-kit | 自己维护镜像与发布周期 |
先检查 backend/go.work、所属 go.mod 及相邻服务，确定新目录是否已被现有模块包含。Core/Things 下的服务通常共用上级模块；生成器创建的独立 go.mod 不能直接保留。
2. 准备生成工具
在授权主仓根目录执行：
bash shell/install-goctl.sh
goctl --version
protoc --version安装脚本固定联犀 goctl 源码与项目补丁；Proto 插件按环境安装准备。生成器版本跟随仓库，不能直接安装最新版替换平台工具。
3. 创建服务骨架
下面是生成器的基础入口，目录名仅作示例。在确认归属的任务工作区执行，生成后先检查差异：
goctl rpc new demosvr --style=goZero -m
goctl api new demoapi --style=goZeroRPC 入口生成后还需按相邻服务整理模块、Proto 包名和 build.sh；-m 用于多 service 组织，不是数据库模型生成开关。HTTP 合同遵循平台的 .api 元数据约定，参考接口权限。
demosvr/
├── proto/ 或 http/ # 原始接口合同
├── build.sh # 定向生成入口
├── etc/ # 运行配置
├── internal/
│ ├── config/ # 配置结构
│ ├── svc/ # 依赖注入
│ ├── logic/ # 接口用例
│ ├── domain/ # 领域逻辑
│ └── repo/ # 数据与外部设施
└── pb/、client/ # RPC 生成物，按服务实际布局internal 不是供其他模块导入的 SDK。跨服务能力通过合同或明确的共享领域入口提供。
4. 接入依赖与启动生命周期
在 NewServiceContext 中装配长期复用的客户端、仓储、缓存及事件总线。配置先解析和校验，再初始化数据库、幂等迁移和业务组件；订阅及定时处理器准备好后，才启动消费并对外提供服务。
- RPC 使用平台的 direct/grpc 分支，详见连接平台服务。
- 数据库连接与种子初始化见数据库开发。
- 缓存和事件订阅在服务启动时注册，不能每个请求重复初始化。
- 后台任务使用受管理的上下文和退出生命周期，不能创建无法停止的全局循环。
如果服务需要作为 AllInOne 模块运行，参照 backend/cmd/ 对应入口的现有模块注册方式，同时准备独立运行所需配置。只有确实属于平台进程的模块才加入该入口。
5. 实现并生成一条接口
- 先定义请求/响应、身份范围、动作权限和错误码。
- 写业务逻辑及仓储，不在生成的 handler/server/pb 中填业务。
- 在自己的
build.sh固定输入合同和生成参数。 - 执行本服务脚本，检查没有创建多余模块或改动其他服务生成物。
- 启动本机隔离依赖，验证正常、无权、重复请求及依赖失败分支。
既有服务生成示例（主仓根目录）：
bash backend/core/service/apisvr/build.sh
bash backend/things/service/dmsvr/build.sh脚本以实际服务为准，二者分别演示 HTTP 和 RPC 生成，并非创建新业务后都要运行。
6. 交付前检查
检查服务是否能从干净工作区生成与启动、启动迁移能否重复执行、进程退出是否关闭连接与消费者，以及该服务是否确实被运行入口加载。数据库迁移由服务启动调用实现，不存在所有服务通用的 go run main.go migrate 命令。
更新日志
2026/10/16 19:46
查看所有更新日志
b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于