# 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`，用于一键拉起依赖的中间件。
```bash
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):**
```text
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` 配置）。