aiot-platform-cloud/docs/technical-overview/08-开发指南.md

Part 8: 开发指南

文档定位：为新入职开发人员提供从环境搭建、代码规范、分支管理到本地调试的保姆级教程，确保开发环境与生产环境的一致性。

8.1 本地开发环境搭建

8.1.1 基础软件要求

软件	版本要求	说明
JDK	17	必须 JDK 17 (Spring Boot 3.x 硬性要求)
Maven	3.8+	建议配置阿里云镜像源
IntelliJ IDEA	2023.2+	需安装 Lombok, MapStruct 插件
Git	2.30+	代码版本管理
Docker	24.0+	用于本地启动中间件 (MySQL, Redis 等)

8.1.2 中间件快速启动

项目根目录下提供了 docker-compose.core.yml，用于一键拉起依赖的中间件。

cd aiot-platform-cloud
docker-compose -f docker-compose.core.yml up -d mysql redis nacos rocketmq tdengine

• MySQL 初始化：首次启动后，需导入 sql/mysql/ 下的 SQL 脚本。
• Nacos 配置：访问 http://localhost:8848/nacos，导入 config/nacos_config_export.zip（假定存在导出配置）。

---

8.2 代码规范 (Code Style)

8.2.1 命名规范

• 类名：UpperCamelCase，如 IotDeviceService。
• 应用名：lower-kebab-case，如 viewsh-module-system。
• 包名：com.viewsh.module.{模块}.{层级}，如 com.viewsh.module.iot.controller。

8.2.2 异常与日志

• 日志：统一使用 @Slf4j。禁止使用 System.out.println。
  • INFO: 关键流程节点、状态变更。
  • ERROR: 异常堆栈，必须包含 e。
• 异常：业务逻辑错误抛出 ServiceException(ErrorCode)，不要吞掉异常。

---

8.3 分支管理策略 (Git Flow)

采用简化的 Git Flow 模型：

• master：主分支，对应生产环境 (Prod)，仅允许从 release 合并。
• release：发布分支，对应预发布环境 (Staging)，进行集成测试。
• dev：开发主分支，对应开发环境 (Dev)。
• feat/xxx：功能分支，从 dev 切出，开发完成后通过 Pull Request (PR) 合并回 dev。

提交规范 (Commit Message):

feat(iot): 新增设备批量导入功能
fix(ops): 修复工单状态流转死锁 bug
docs: 更新部署文档
style: 代码格式化

---

8.4 如何新增一个微服务

1. 创建 Module：在 viewsh-module-xxx 下创建 Maven 子模块。
2. 依赖配置：引入 viewsh-common 及相关 starter。
3. 配置文件：在 resources 下创建 bootstrap.yaml，配置 Nacos 地址。
4. 启动类：添加 @SpringBootApplication 和 @EnableDiscoveryClient。
5. 网关路由：在 Nacos 配置中心的 viewsh-gateway 路由配置中添加转发规则。

---

8.5 常见问题排查 (FAQ)

Q: 启动报 Connection refused: no further information? A: 检查 Nacos 是否启动成功，且 8848 端口未被防火墙拦截。

Q: Maven 依赖下载失败? A: 检查 pom.xml 中的 Maven 仓库配置，确认 settings.xml 中 mirror 设置正确。

Q: MapStruct 转换对象时属性为 null? A: 确保编译顺序：Lombok 必须在 MapStruct 之前执行（参考父工程 pom.xml 的 maven-compiler-plugin 配置）。