81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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` 配置）。
|