可以把技能放到本机用户目录的 ~/.cursor/skills/<技能目录>/（Windows 一般是 C:\Users\你的用户名\.cursor\skills\）。这样任意项目打开后，只要 Cursor 会加载用户级 skills，就不必每个仓库复制一份。
注意：~/.cursor/skills-cursor/ 是 Cursor 内置技能目录，不要把自己的技能放进去；自定义技能用 项目 .cursor/skills/ 或 用户 ~/.cursor/skills/。
在项目的根目录下创建：.cursor\skills\project-structure-scaffold
# 结构参考
## 解析仓库信息
生成代码前从工作区读取：
| 项 | 来源 |
|----|------|
| 子模块列表 | 根 `pom.xml` → `<modules>` |
| `groupId` / Java 版本 / Spring Boot 版本 | 根 `pom.xml` → `<properties>`、`<parent>` |
| `{basePackage}` | 任意现有 `@SpringBootApplication` 或 `@RestController` 的 `package` 根前缀 |
| DTO 布局 | 列出目标模块 `dto/` 目录结构，对照 SKILL §2 |
| Mapper 扫描路径 | 目标模块启动类上的 `@MapperScan` |
| 统一响应类型 | 同模块 Controller 方法的返回类型 |
---
## 新建 Maven 子模块
### 1. 根 pom 注册
```xml
<module>{module-name}</module>
```
### 2. 子模块 pom.xml 骨架
复制**同类型已有模块**的 `pom.xml`，修改 `<artifactId>`；保留相同的 `<parent>` 与 `relativePath`。
最小 Web 模块示例：
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>{groupId}</groupId>
<artifactId>{parent-artifactId}</artifactId>
<version>${revision}</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>{module-name}</artifactId>
<dependencies>
<!-- 从同类型模块复制：web、validation、mybatis-plus、redis 等 -->
</dependencies>
</project>
```
### 3. 启动类
路径：`{module-name}/src/main/java/{basePackage}/{Module}Application.java`
```java
package {basePackage};
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class {Module}Application {
public static void main(String[] args) {
SpringApplication.run({Module}Application.class, args);
}
}
```
若需 MyBatis，追加与同模块一致的 `@MapperScan("...")`。
### 4. 资源目录
复制同类型模块的 `application.yml` 骨架，修改 `spring.application.name` 与 `server.port`。
---
## DTO 布局识别
在目标模块执行目录/list，按特征匹配：
| 特征 | 布局 |
|------|------|
| 存在 `dto/request/` 与 `dto/response/` | A |
| 存在 `dto/{scope}/` 且无 request 根目录 | B |
| `dto/` 下直接放 `*Request`/`*Response` | C |
新 scope 的包名与深度**对齐最近邻**已有 scope。
---
## 持久化约定（MyBatis-Plus 常见形态）
以目标模块 `application.yml` 中 `mybatis-plus` 段为准；常见项：
```yaml
mybatis-plus:
mapper-locations: classpath*:/mapper/**/*.xml
type-aliases-package: {entity-package}
configuration:
map-underscore-to-camel-case: true
global-config:
db-config:
id-type: AUTO
logic-delete-field: deleted
logic-delete-value: 1
logic-not-delete-value: 0
```
- Entity：`@TableName("snake_case")`、`@TableId`
- Mapper：`extends BaseMapper<Entity>`
- 状态码常量：可放在 Entity 内 `public static final`
---
## scope / integration 子包命名
| 层级 | 约定 |
|------|------|
| 子包名 | 全小写、短、与现有子包同级风格一致 |
| 类名 | PascalCase，前缀表达功能 scope |
| 表名 | snake_case |
| 配置 prefix | 点分层级，与 Properties 类 `prefix` 一致 |
新子包创建前：**搜索目标模块内已有同级子包**，新代码与之对齐。
---
name: project-structure-scaffold
description: Scaffolds Maven multi-module Spring Boot projects with standard Java package trees and class naming. Use when creating modules, layers (controller/service/client/dto/entity/mapper), package layout, or when the user asks for 项目目录结构、包名、新建模块、分层脚手架、Java 包规范.
---
# Maven 多模块项目目录与包结构脚手架
在仓库中新建子模块、功能域或分层类时，**先确定目标模块与现有分层风格**，再生成目录与 `package`；**禁止**自造与目标模块现有代码冲突的包层级。
## 0. 模块选型
| 场景 | 做法 |
|------|------|
| 在已有可部署模块中扩展 | 打开根 `pom.xml` 的 `<modules>`，选定 **artifactId** 对应的子工程 |
| 跨模块共享持久化 | 独立 **dao** / **dto** 类 jar（若仓库已有此类模块） |
| 跨模块共享工具与统一响应 | 独立 **common** 类 jar（若仓库已有） |
| 全新可部署服务 | 新建 `{module}/` 子工程 | 见 [reference.md](reference.md) |
**选定模块后**：在工作区搜索**同模块、同层级**的现有类（Controller / Service / Client / Mapper）作为模板；包名、类名、配置前缀均从仓库解析，**不要**从本文档抄写占位符为真实名称。
**技术栈**：以根 POM 为准（Java 版本、Spring Boot 版本、`groupId`、`artifactId` 父坐标）。
---
## 1. 标准源码树（Spring Boot 可部署模块）
```
{module}/
├── pom.xml
└── src/main/
├── java/{basePackage}/
│ ├── {Module}Application.java # 启动类，根包下
│ ├── controller/ # REST 入口
│ ├── service/ # 接口；可按 scope 分子包 service/{scope}/
│ │ └── impl/ # *ServiceImpl
│ ├── client/ # 外部 HTTP/RPC 调用
│ │ └── {integration}/ # 按集成目标分子包
│ │ ├── request/ # 出站请求模型（可选）
│ │ ├── response/ # 出站响应模型（可选）
│ │ └── util/ # 客户端专用工具（可选）
│ ├── config/ # @Configuration、*Properties
│ ├── constant/ # 常量类
│ ├── dto/ # 入站 API 模型（布局见 §2）
│ ├── entity/ # 持久化实体
│ ├── mapper/ # 数据访问接口
│ ├── enums/ # 枚举；可按 scope 分子包
│ ├── wrapper/ # 模型转换（若项目有 Wrapper 基类）
│ ├── util/ # 模块内工具
│ ├── except/ # 模块级异常处理（若项目使用该包名）
│ ├── strategy/ # 链式/策略处理（可选）
│ │ ├── handler/{scope}/
│ │ └── context/{scope}/
│ ├── task/ # 定时任务（可选）
│ └── vo/ # 视图/展示模型（可选）
└── resources/
├── application.yml
├── application-{profile}.yml # 按仓库现有 profile 命名
└── logback-spring.xml # 若仓库使用
```
**Mapper 扫描**：若使用 MyBatis / MyBatis-Plus，在启动类添加 `@MapperScan`，扫描路径与**同模块现有启动类**一致。
---
## 2. 入站 DTO 包布局（三选一，与同模块保持一致）
先列出目标模块 `dto/` 下现有子包，匹配下列**结构特征**，不要混用多种布局。
### 布局 A：request / response 分目录
```
{basePackage}.dto.request.{scope} → *Request
{basePackage}.dto.response.{scope} → *Response
```
### 布局 B：按 scope 聚合
```
{basePackage}.dto.{scope} → 该 scope 下 DTO
{basePackage}.dto.{scope}.request|response → 需要再细分时
{basePackage}.dto.{shared}.* → 跨 scope 共享协议
```
### 布局 C：扁平 dto 包
```
{basePackage}.dto.* → Request/Response 同包，无 request 子目录
```
### 出站 Client 模型
与 Controller 入站 DTO **分包**：
```
{basePackage}.client.request.{integration}.*
{basePackage}.client.response.{integration}.*
```
或 `{basePackage}.client.{integration}.*`（以仓库现有 client 包为准）。
---
## 3. 命名约定
| 类型 | 模式 | 占位 |
|------|------|------|
| 启动类 | `{Module}Application` | — |
| Controller | `{Feature}Controller` | — |
| URL 路径 | kebab-case | `/api/{resource}` |
| Service | `{Feature}Service` / `{Feature}ServiceImpl` | impl 在 `service/impl/` 或 `service/{scope}/impl/` |
| 配置类 | `{Feature}Properties` | `@ConfigurationProperties(prefix = "...")` |
| 入站 Request | `{Feature}{Action}Request` | — |
| 入站 Response | `{Feature}{Action}Response` | — |
| 出站 Client | `{Integration}Client` / `{Integration}ApiClient` | — |
| Entity | PascalCase | — |
| 表名 | snake_case | `@TableName` |
| Mapper | `{Entity}Mapper` | — |
| Wrapper | `{Entity}Wrapper` / `{Feature}Wrapper` | — |
| 常量类 | `{Feature}Constants` | — |
| scope 子包 | 全小写短名 | `{scope}`、`{integration}` |
**注解与依赖**：Controller/Service 注入方式、统一响应类型、校验注解（`@Valid`、`@Validated`）——**复制同模块现有 Controller** 的写法。
---
## 4. 新功能脚手架流程
```
进度:
- [ ] 1. 确定目标模块（§0）
- [ ] 2. 确定 scope / integration 子包名（全小写，与现有子包风格一致）
- [ ] 3. 对照同模块，选定 DTO 布局（§2）
- [ ] 4. 创建 config/*Properties + application*.yml 配置项
- [ ] 5. 创建 client/{integration}/*Client（若有外部调用）
- [ ] 6. 创建 dto/* Request/Response
- [ ] 7. 创建 service/{scope}/*Service + impl
- [ ] 8. 创建 controller/*Controller
- [ ] 9. 若持久化：entity + mapper（+ wrapper）
- [ ] 10. 若链式处理：strategy 子包（或项目内等价包）
```
### 4.1 典型文件清单（含持久化）
| 文件 | 包 |
|------|-----|
| `{Feature}Controller` | `controller` |
| `{Feature}Service` | `service` 或 `service.{scope}` |
| `{Feature}*Request/Response` | 按 §2 |
| `{Integration}Client` | `client.{integration}` |
| `{Feature}Properties` | `config` |
| `{Feature}Record`（entity） | `entity` |
| `{Feature}RecordMapper` | `mapper` |
| `{Feature}Wrapper` | `wrapper` |
---
## 5. 共享模块（若仓库存在）
| 模块类型 | 典型职责 | 包模式 |
|----------|----------|--------|
| common | 统一响应、异常、分页基类、公共配置 | `{basePackage}.{layer}` |
| common-dao | 跨模块 entity / mapper / enums | `{basePackage}.{module}.entity` 等 |
| common-dto | 跨模块查询/响应 DTO | `{basePackage}.dto.{module}` |
**原则**：仅单模块使用的 entity/dto 放在**该模块内**；多模块复用再放入共享 jar。
---
## 6. 检查清单
- [ ] `package` 前缀与目标模块现有类一致
- [ ] 未在 common jar 中引入仅 Web 模块需要的依赖（除非已有先例）
- [ ] Controller 不直连 Mapper
- [ ] 入站 dto 与 client 出站模型不混包
- [ ] 配置 `prefix` 与 yml 键一致
- [ ] 新子模块已在根 `pom.xml` `<modules>` 注册，`relativePath` 指向父 POM
---
## 7. 协作 Skill
| 场景 | 说明 |
|------|------|
| 责任链 / 处理器链 | 使用项目内 `chain-of-responsibility-expert`（若已配置） |
| 分页 + 导出 | 使用项目内 `spring-admin-page-export`（若已配置） |
---
## 附加资源
- 新建子模块 POM 模板、DTO 布局识别、持久化约定：[reference.md](reference.md)