平台后端开发
约 1094 字大约 4 分钟
2026-10-16
平台后端修改从所属服务进入，遵循该服务已有的领域、持久化和错误处理方式。独立应用调用平台 RPC 的方法另见SDK 接入。
按任务查阅专题
| 当前工作 | 详细教程 |
|---|---|
| 新建服务、调整配置或调用其他服务 | 初始化 · 配置 · RPC |
| 新接口鉴权、资源与数据隔离 | 中间件 · 接口权限 · 数据权限 |
| 数据持久化与读写性能 | 数据库 · 缓存 |
| 异步业务与周期处理 | 事件总线 · 定时任务 |
| 附件和外部系统扩展 | 对象存储 · Hook |
| 实时通信和物联网数据 | WebSocket · 设备消息 · 数据分析 |
完成一条平台接口
- 确认所属 Core/Things 服务，定义请求、响应、动作权限、企业与项目范围。
- 在
.api或.proto修改合同，通过该服务build.sh生成接口代码。 - 在对应 logic/领域层实现业务，复用现有仓储与错误码，补集成测试。
- 同步受影响的前端 SDK、权限资源和公开合同，按合同维护检查差异。
Core 对外 REST 统一使用 /api/v1/system/，Things 使用 /api/v1/things/。接口描述应明确业务语义、必填字段、动作与权限；新 API 使用当前项目约定，不照抄旧文章的路由和生成模板。
身份与数据权限
外部用户身份须经过平台中间件验证。业务从已认证上下文取得企业、用户与项目，不信任请求体或外部自报的内部身份头。
- 查询与写入同时限定企业和业务资源范围，不能只用传入的对象 ID 更新数据。
- 产品、设备、项目、区域的授权使用所属服务现有检查入口，不能把“已登录”当作“可控制设备”。
- 管理员、普通成员、只读成员与跨企业请求分别验证，后台任务领取后重新绑定记录所属企业再处理。
- Go
internal包只能在其允许的源码范围内调用，不能写成第三方服务可直接导入的 SDK。
数据模型与迁移
数据库操作携带请求上下文，企业字段、可空字段和软删除遵循模块现有类型。新表、默认配置、种子数据和存量数据变更通过服务启动时的幂等迁移收敛。
迁移至少验证：空库启动、已有库升级、重复启动、唯一约束、失败后的重试，以及旧版本程序对新增字段的读取兼容。外部通知、RPC 和对象存储不与数据库写入天然原子；需要可靠投递时采用持久任务和幂等键。
消息、缓存和任务
| 能力 | 平台开发要求 |
|---|---|
| 事件总线 | 核对主题、消息信封、订阅生命周期和失败处理；持久需求使用对应持久机制 |
| 缓存 | 键包含正确业务范围，写入后失效或刷新，验证并发加载与空值语义 |
| 定时任务 | 业务周期任务通过 timedsvr 的注册入口调度，处理器先就绪，再启用任务 |
| 外部调用 | 有超时、认证、错误分类与可重试边界；不记录完整令牌 |
定时触发不替代业务幂等。重复触发、重启恢复和并发领取必须得到可解释的业务结果。平台内的 SDK/仓储对象不能原样暴露为独立应用的运行依赖。
生成与验证示例
以下命令从主仓根目录执行，生成只在修改对应合同后进行：
# 示例：重新生成 Things 设备管理服务合同。
bash backend/things/service/dmsvr/build.sh
# 示例：仅验证本次涉及的业务包。
cd backend
go test ./things/service/dmsvr/internal/logic/projectmanage/...不同服务可能是不同 Go module，测试从能覆盖该模块的 workspace 位置运行。重任务使用仓库资源门禁。提交前审阅生成差异，出现无关的大量变化时检查工具版本；不要直接修改 pb 或用全量重生成掩盖问题。
更新日志
2026/10/16 19:46
查看所有更新日志
b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于1a4a7-docs(开发指南): 重建平台与应用开发路线于