3.3 KiB
3.3 KiB
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 如何新增一个微服务
- 创建 Module：在
viewsh-module-xxx下创建 Maven 子模块。 - 依赖配置：引入
viewsh-common及相关 starter。 - 配置文件：在
resources下创建bootstrap.yaml，配置 Nacos 地址。 - 启动类：添加
@SpringBootApplication和@EnableDiscoveryClient。 - 网关路由：在 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 配置）。