主题
项目结构与编译指南
项目结构
创建的项目采用多模块 Maven 架构：
{projectName}/
├── {projectName}-api/ # API 接口模块
│ ├── src/main/java/ # Controller、DTO
│ └── pom.xml
├── {projectName}-business/ # 业务逻辑模块
│ ├── src/main/java/ # Service、Manager
│ └── pom.xml
├── {projectName}-domain/ # 数据访问模块
│ ├── src/main/java/ # Mapper、Entity
│ ├── src/main/resources/ # Mapper XML
│ └── pom.xml
├── {projectName}-start/ # 启动模块
│ ├── src/main/java/ # Application 主类
│ ├── src/main/resources/ # application.yml
│ └── pom.xml
└── pom.xml # 父 POM（依赖管理）模块职责
| 模块 | 职责 | 典型内容 |
|---|---|---|
| api | 对外接口层 | Controller、Request/Response DTO、VO |
| business | 业务逻辑层 | Service 实现、业务规则、事务管理 |
| domain | 数据访问层 | Mapper 接口、Entity 实体、MyBatis XML |
| start | 应用启动层 | Spring Boot 主类、配置文件、依赖引入 |
编译验证流程
标准编译命令
bash
# 进入项目目录
cd <project-name>
# 清理并编译（推荐）
mvn clean compile
# 清理、编译并安装到本地仓库
mvn clean install
# 仅编译特定模块
mvn clean compile -pl <project-name>-start编译结果判断
| 输出 | 含义 | 下一步操作 |
|---|---|---|
BUILD SUCCESS | 编译成功 | ✅ 可以开始开发 |
BUILD FAILURE | 编译失败 | 🔧 执行自动诊断与修复 |
常见编译错误及修复
A. 依赖缺失问题
错误特征：
[ERROR] Failed to execute goal on project xxx:
Could not resolve dependencies for project xxx修复步骤：
- 检查父 POM 中的
<dependencyManagement>是否正确 - 检查子模块的
pom.xml中依赖声明是否完整 - 执行依赖更新：bash
mvn dependency:resolve mvn clean install -U # -U 强制更新快照 - 检查网络连接或 Maven 仓库配置（
~/.m2/settings.xml）
B. 代码语法错误
错误特征：
[ERROR] /path/to/File.java:[line,col] cannot find symbol
[ERROR] /path/to/File.java:[line,col] incompatible types
[ERROR] /path/to/File.java:[line,col] method does not override修复步骤：
- 定位到具体的类和行号
- 读取错误文件内容
- 根据错误信息修正代码：
cannot find symbol→ 检查 import 语句或类名拼写incompatible types→ 检查类型转换或泛型声明method does not override→ 检查方法签名或父类/接口定义
- 重新执行编译验证
C. 配置文件错误
错误特征：
[ERROR] Failed to load ApplicationContext
[ERROR] Property 'xxx' not found修复步骤：
- 检查
application.yml或application.properties格式（注意缩进） - 验证必填配置项是否存在（如数据库连接、Redis 地址）
- 检查占位符
${...}是否正确解析 - 修复配置后重新编译
D. Maven/Java 版本问题
错误特征：
[ERROR] Unsupported class file major version xx
[ERROR] requires at least Java 11修复步骤：
- 检查当前 Java 版本：bash
java -version - 检查
pom.xml中的<java.version>配置 - 如果不匹配，选择以下方案：
- 升级/降级 JDK 版本
- 修改
pom.xml中的 Java 版本配置
- 执行清理后重新编译：bash
mvn clean mvn compile
编译失败时的处理流程
如果自动修复无法解决问题：
保存完整错误日志
bashmvn clean compile > build-error.log 2>&1提供详细的诊断报告，包括：
- 错误类型和位置
- 影响的具体模块
- 已尝试的修复步骤
- 建议的手动解决方案
引导用户查看日志并提供进一步帮助
诊断报告示例
❌ 自动修复未能解决编译问题
📋 诊断报告：
- 错误类型：依赖解析失败
- 影响模块：my-project-domain
- 缺失依赖：com.digitalhainan:dh-common-utils:1.0.0-SNAPSHOT
🔧 已尝试的修复：
1. 执行 mvn dependency:resolve
2. 执行 mvn clean install -U
3. 检查 Maven 仓库配置
💡 建议操作：
1. 检查私有 Maven 仓库是否可访问
2. 确认 dh-common-utils 是否已正确发布
3. 查看详细错误日志：build-error.log
需要我帮您进一步排查吗？后续开发建议
编译成功后，可以开始开发和测试项目。
1. 启动项目
方式一：使用 Maven 命令
bash
mvn spring-boot:run -pl <project-name>-start方式二：在 IDE 中运行
- 打开
<project-name>-start模块 - 找到
Application主类（通常命名为{ProjectName}Application） - 右键点击 → Run 或 Debug
注意事项：
- ⚠️ 不要自动执行启动命令：启动服务是长时间运行的阻塞操作，应引导用户手动决定何时启动
- 首次启动可能需要下载依赖，请耐心等待
- 确保端口 8080 未被其他程序占用
2. 验证项目启动
项目启动成功后，控制台会显示类似信息：
Started {ProjectName}Application in X.XXX seconds3. 访问 Swagger 接口文档
大多数 Spring Boot 项目集成了 Swagger/Knife4j 文档工具。
重要：AI 应动态识别配置
在提供访问指引前，AI 必须：
- 读取
application.yml或application.properties - 提取
server.port和server.servlet.context-path - 根据实际配置生成准确的 URL
详细配置解析逻辑：查看 references/swagger-config.md
常见访问地址模板：
| 文档类型 | URL 模板 |
|---|---|
| Knife4j（推荐） | http://localhost:{port}/{context-path}doc.html |
| Swagger UI | http://localhost:{port}/{context-path}swagger-ui.html |
| Swagger JSON | http://localhost:{port}/{context-path}v2/api-docs |
参数说明：
{port}：从server.port提取，默认8080{context-path}：从server.servlet.context-path提取，默认为空
如果无法访问：
- 检查项目是否集成了 Swagger/Knife4j 依赖
- 确认 AI 是否正确读取了配置文件
- 检查 Swagger 配置是否启用（检查
swagger.enable或类似配置） - 查看项目
README.md或文档说明确认具体访问路径
Swagger 验证步骤：
- 浏览器访问上述地址
- 查看接口列表是否正常加载
- 尝试调用一个简单的接口（如健康检查
/actuator/health） - 确认返回结果符合预期
4. 其他常用操作
运行测试
bash
mvn test打包部署
bash
mvn clean package
# 生成的 JAR 文件位于：<project-name>-start/target/查看项目文档
- 阅读
README.md了解项目说明 - 检查
docs/目录（如果有） - 查看
pom.xml了解项目依赖