From a4f8964de246ebd531f7595c80f60fe01df91c99 Mon Sep 17 00:00:00 2001 From: lroyia Date: Fri, 10 Apr 2026 14:36:12 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20chinaweal-quicknot?= =?UTF-8?q?e=20=E5=92=8C=20load-codestyle=20=E4=B8=A4=E4=B8=AA=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在 marketplace.json 中注册新 skill - 更新 README.md 说明文档 --- .claude-plugin/marketplace.json | 16 + README.md | 22 + skills/chinaweal-quicknote/SKILL.md | 450 ++++++++++++++++++ skills/load-codestyle/README.md | 64 +++ skills/load-codestyle/SKILL.md | 148 ++++++ .../style/java/java-code-style.md | 338 +++++++++++++ 6 files changed, 1038 insertions(+) create mode 100644 skills/chinaweal-quicknote/SKILL.md create mode 100644 skills/load-codestyle/README.md create mode 100644 skills/load-codestyle/SKILL.md create mode 100644 skills/load-codestyle/style/java/java-code-style.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 52319b2..977111d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -22,6 +22,22 @@ "skills": [ "./gitea-api" ] + }, + { + "name": "chinaweal-quicknote", + "source": "./skills", + "strict": false, + "skills": [ + "./chinaweal-quicknote" + ] + }, + { + "name": "load-codestyle", + "source": "./skills", + "strict": false, + "skills": [ + "./load-codestyle" + ] } ] } diff --git a/README.md b/README.md index 97da667..eb8348c 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,28 @@ Gitea API 调用工具。用于与 Gitea 代码托管平台进行交互。 --- +### chinaweal-quicknote + +众望通 PMS 系统速记相关 API 工具。用于管理个人速记、标签和附件。 + +**触发场景**: 速记、新增速记、查询速记、删除速记、速记标签、附件上传/下载 + +**前置要求**: 需要配置环境变量 `CHINAWEAL_PMS_TOKEN` + +**API 基础地址**: `https://www.chinaweal.com.cn/pms-api` + +--- + +### load-codestyle + +代码风格参考文件加载工具。用于加载指定语言的代码风格规范。 + +**触发场景**: 加载代码风格、加载 Java 代码风格 + +**使用方式**: `/load-codestyle` 或 `/load-codestyle java` + +--- + ## 安装 ### 方式一：Claude Code 插件市场安装（推荐） diff --git a/skills/chinaweal-quicknote/SKILL.md b/skills/chinaweal-quicknote/SKILL.md new file mode 100644 index 0000000..c59c563 --- /dev/null +++ b/skills/chinaweal-quicknote/SKILL.md @@ -0,0 +1,450 @@ +--- +name: chinaweal-quicknote +description: | + 众望通 PMS 系统速记相关 API 工具。用于管理个人速记、标签和附件。 + + 当用户提到以下场景时使用此 Skill： + (1) 速记、新增速记、查询速记、删除速记 + (2) 速记标签管理 + (3) 速记附件上传/下载/删除 + (4) 发送企业微信通知 + (5) 用户提到 "速记"、"quicknote"、"快记" +version: 1.0.0 +license: Apache-2.0 +metadata: + author: lirh + category: development + tags: + - pms + - chinaweal + - quicknote + - notes +--- + +# ChinaWeal 速记 API + +## 概述 + +此 Skill 用于调用众望通 PMS 系统的速记相关 API，包括速记管理、标签管理、附件管理和消息通知。 + +## 认证配置 + +使用此 Skill 前，需要配置环境变量 `CHINAWEAL_PMS_TOKEN`： + +- **环境变量名称**: `CHINAWEAL_PMS_TOKEN` +- **用途**: PMS 系统的用户授权 Token + +### 请求鉴权方式 + +所有 API 请求需要在请求头中携带 Authorization 信息： + +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +## Base URL + +``` +https://www.chinaweal.com.cn/pms-api +``` + +## 功能清单 + +### 功能1: 新增速记 + +创建一条新的速记记录。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/save` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +Content-Type: application/json +``` + +**请求体 (PmsQuickNote)**: +| 字段 | 类型 | 描述 | +|------|------|------| +| noteContent | string | 速记内容 | +| noteDate | string (date) | 速记日期，格式: yyyy-MM-dd | +| noteTime | string (date-time) | 速记时间 | +| tagNames | array[string] | 标签列表 | +| tagNamesStr | string | 标签名称字符串，用逗号分隔 | + +**响应**: `RestResultPmsQuickNote` +- `code` - 状态码 +- `msg` - 消息 +- `data` - 创建的速记对象 + +**使用示例**: +``` +帮我新增一条速记 +创建一条速记，内容是今天完成了xxx +新增速记：完成了项目评审 +``` + +### 功能2: 更新速记 + +更新已有的速记记录。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/update` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +Content-Type: application/json +``` + +**请求体 (PmsQuickNote)**: +| 字段 | 类型 | 描述 | +|------|------|------| +| id | string | 速记ID（必填） | +| noteContent | string | 速记内容 | +| noteDate | string (date) | 速记日期 | +| noteTime | string (date-time) | 速记时间 | +| tagNames | array[string] | 标签列表 | +| tagNamesStr | string | 标签名称字符串，用逗号分隔 | + +**响应**: `RestResultPmsQuickNote` + +**使用示例**: +``` +更新速记 ID 为 xxx 的内容 +修改速记：把内容改成xxx +``` + +### 功能3: 删除速记 + +删除指定的速记记录。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/delete` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**查询参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| id | string | 速记ID（必填） | + +**响应**: `RestResultObject` + +**使用示例**: +``` +删除速记 ID 为 xxx +删除速记 +``` + +### 功能4: 分页查询速记列表 + +分页查询速记列表，支持按日期、内容、标签筛选。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/list` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +Content-Type: application/json +``` + +**请求体 (BaseQueryPmsQuickNoteQueryDTO)**: +| 字段 | 类型 | 描述 | +|------|------|------| +| entity.noteDate | string (date) | 速记日期，格式: yyyy-MM-dd | +| entity.noteContent | string | 速记内容（模糊搜索） | +| entity.tagName | string | 标签名称 | +| current | integer | 当前页 | +| size | integer | 每页显示条数 | +| orderFields | array[string] | 排序字段 | +| orderSorts | array[string] | 排序规则 (asc/desc) | + +**响应**: `RestResultIPagePmsQuickNote` +- `data.records` - 速记列表 +- `data.total` - 总记录数 +- `data.current` - 当前页 +- `data.size` - 每页条数 + +**使用示例**: +``` +查询速记列表 +查看最近一周的速记 +按标签筛选速记 +查找包含xxx的速记 +``` + +### 功能5: 查询速记详情 + +根据速记ID查询详情。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/detail/{id}` + +**请求方法**: GET + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**路径参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| id | string | 速记ID（必填） | + +**响应**: `RestResultPmsQuickNote` + +**使用示例**: +``` +查询速记 xxx 的详情 +查看速记 ID 为 xxx 的详细信息 +``` + +### 功能6: 获取速记的标签列表 + +根据速记ID获取该速记的所有标签。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/tag/{noteId}` + +**请求方法**: GET + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**路径参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| noteId | string | 速记ID（必填） | + +**响应**: `RestResultListString` - 标签列表 + +**使用示例**: +``` +获取速记 xxx 的标签 +查看速记的标签列表 +``` + +### 功能7: 获取前10个常用标签 + +获取当前用户使用最多的前10个标签。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/tag/list` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +Content-Type: application/json +``` + +**响应**: `RestResultListString` - 标签列表 + +**使用示例**: +``` +获取我常用的标签 +查看我使用最多的标签 +``` + +### 功能8: 上传速记附件 + +为速记上传附件。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/upload` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +Content-Type: application/json +``` + +**查询参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| noteId | string | 速记ID（必填） | + +**请求体**: +| 字段 | 类型 | 描述 | +|------|------|------| +| file | string | 上传的文件（base64或binary） | + +**响应**: `RestResultPmsQuickNoteAttachment` + +**使用示例**: +``` +上传附件到速记 xxx +为速记添加附件 +``` + +### 功能9: 获取速记附件列表 + +获取指定速记的所有附件。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/list/{noteId}` + +**请求方法**: GET + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**路径参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| noteId | string | 速记ID（必填） | + +**响应**: `RestResultListPmsQuickNoteAttachment` + +**附件字段**: +| 字段 | 类型 | 描述 | +|------|------|------| +| id | string | 附件ID | +| noteId | string | 速记ID | +| fileName | string | 文件名 | +| fileFormat | string | 文件格式 | +| fileSize | integer | 文件大小(字节) | +| createTime | string | 创建时间 | + +**使用示例**: +``` +获取速记 xxx 的附件列表 +查看速记有哪些附件 +``` + +### 功能10: 下载速记附件 + +下载指定的速记附件。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/download/{attachmentId}` + +**请求方法**: GET + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**路径参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| attachmentId | string | 附件ID（必填） | + +**响应**: 文件内容 (byte) + +**使用示例**: +``` +下载附件 xxx +下载速记附件 +``` + +### 功能11: 删除速记附件 + +删除指定的速记附件。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/delete` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**查询参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| attachmentId | string | 附件ID（必填） | + +**响应**: `RestResultObject` + +**使用示例**: +``` +删除附件 xxx +删除速记附件 +``` + +### 功能12: 发送企业微信通知 + +发送企业微信消息通知。 + +**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/notice/entwx/send` + +**请求方法**: POST + +**请求头**: +``` +Authorization: Bearer {CHINAWEAL_PMS_TOKEN} +``` + +**查询参数**: +| 参数 | 类型 | 描述 | +|------|------|------| +| message | string | 消息内容（必填） | + +**响应**: `RestResultObject` + +**使用示例**: +``` +发送企业微信消息 xxx +发送通知：xxx +``` + +## 调用方式 + +使用 Bash 工具执行 curl 命令进行 API 调用。 + +### 环境变量 + +```bash +CHINAWEAL_PMS_TOKEN="your-token-here" +``` + +### 示例命令 + +**新增速记**: +```bash +curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/save" \ + -H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"noteContent":"今天完成了项目评审","noteDate":"2026-04-10","tagNames":["工作","项目"]}' +``` + +**查询速记列表**: +```bash +curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/list" \ + -H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"current":1,"size":10}' +``` + +**查询速记详情**: +```bash +curl -X GET "https://www.chinaweal.com.cn/pms-api/api/quicknote/detail/{id}" \ + -H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" +``` + +**删除速记**: +```bash +curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/delete?id={id}" \ + -H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" +``` + +## 注意事项 + +1. 确保环境变量 `CHINAWEAL_PMS_TOKEN` 已正确配置 +2. 速记ID `id` 需要从 PMS 系统获取 +3. 日期格式：`noteDate` 使用 `yyyy-MM-dd` 格式 +4. 附件上传大小限制请参考 PMS 系统配置 diff --git a/skills/load-codestyle/README.md b/skills/load-codestyle/README.md new file mode 100644 index 0000000..8eb7303 --- /dev/null +++ b/skills/load-codestyle/README.md @@ -0,0 +1,64 @@ +# load-codestyle + +加载指定语言的代码风格参考文件。 + +## 目录结构 + +``` +load-codestyle/ +├── SKILL.md # Skill 定义文件 +├── README.md # 本文件 +├── style/ # 代码风格文件目录 +│ ├── java/ +│ │ └── java-code-style.md +│ ├── python/ +│ │ └── python-code-style.md +│ └── ... # 可按需添加更多语言 +└── memory/ # 记忆文件目录（自动生成） + └── codestyle-{language}.md +``` + +## 使用方式 + +### 触发命令 + +- `/load-codestyle` +- `/load-codestyle java` +- "加载代码风格" +- "加载 Java 代码风格" + +### 加载文件的路径 + +代码风格文件应放在： +``` +~/.claude/skills/load-codestyle/style/{language}/*.md +``` + +例如 Java 语言： +``` +~/.claude/skills/load-codestyle/style/java/*.md +``` + +## 添加新的语言风格 + +1. 在 `style/` 目录下创建对应语言的文件夹 +2. 添加 `.md` 格式的风格文件 +3. 可以添加多个文件，会全部加载 + +示例： +``` +style/ +├── java/ +│ ├── naming-conventions.md +│ ├── spring-boot-guidelines.md +│ └── database-standards.md +├── python/ +│ └── python-code-style.md +└── go/ + └── go-code-style.md +``` + +## 已支持的语言 + +- Java（示例文件已添加） +- 可按需扩展其他语言 diff --git a/skills/load-codestyle/SKILL.md b/skills/load-codestyle/SKILL.md new file mode 100644 index 0000000..c88c67a --- /dev/null +++ b/skills/load-codestyle/SKILL.md @@ -0,0 +1,148 @@ +--- +name: load-codestyle +description: "加载指定语言的代码风格参考文件。Loads code style reference files for a specified language from skill目录/style/{language}/*.md" +argument-hint: "[language]" +version: "1.0.0" +user-invocable: true +allowed-tools: Read, Glob, Bash +--- + +# 代码风格加载器 (Code Style Loader) + +## 触发条件 + +当用户说以下任意内容时启动： +- `/load-codestyle` +- "加载代码风格" +- "加载{语言}代码风格" +- "查看代码风格规范" + +## 功能说明 + +本 Skill 负责从指定目录加载代码风格参考文件，并将其内容作为当前代码审查和编写的参考依据。 + +## 核心逻辑 + +### Step 1：确定语言 + +用户可以通过以下方式指定语言： +- 直接在命令中指定：如 `/load-codestyle java` +- 在对话中提及：如 "加载 Java 代码风格" +- 如果用户未指定，询问用户希望加载哪种语言的代码风格 + +### Step 2：查找风格文件 + +在以下位置查找代码风格文件： + +**目录结构**： +``` +{skill目录}/style/{language}/*.md +``` + +其中： +- `{skill目录}` 是技能配置的基础目录，默认为 `~/.claude/skills/load-codestyle/` +- `{language}` 是语言名称小写，如 `java`、`python`、`javascript`、`go` 等 + +**实际查找路径**： +``` +~/.claude/skills/load-codestyle/style/{language}/*.md +``` + +### Step 3：加载文件内容 + +1. 使用 `Glob` 工具查找匹配的文件 +2. 使用 `Read` 工具读取每个匹配的文件 +3. 汇总所有文件内容 + +### Step 4：输出结果 + +向用户展示： +``` +已加载 {语言} 代码风格参考文件： + +文件列表： +- file1.md +- file2.md +... + +--- +{文件1内容} +--- +{文件2内容} +--- +... +``` + +### Step 5：保存为上下文 + +将加载的风格文件内容保存到会话记忆中，以便后续代码审查和编写参考： + +参考 `~/.claude/skills/load-codestyle/memory/codestyle-{language}.md` + +## 支持的语言 + +| 语言 | 目录 | +|------|------| +| Java | `style/java/*.md` | +| Python | `style/python/*.md` | +| JavaScript | `style/javascript/*.md` | +| TypeScript | `style/typescript/*.md` | +| Go | `style/go/*.md` | +| C/C++ | `style/c/*.md` | +| Rust | `style/rust/*.md` | +| Kotlin | `style/kotlin/*.md` | + +## 错误处理 + +- **目录不存在**：`style/{language}/` 目录不存在时，提示用户并列出已支持的目录 +- **没有找到文件**：目录存在但没有 `.md` 文件时，提示用户 +- **权限错误**：无法读取文件时，提示具体的权限问题 + +## 使用示例 + +``` +用户：/load-codestyle java + +助手：已加载 Java 代码风格参考文件： + +文件列表： +- naming-conventions.md +- spring-boot-guidelines.md + +--- +# Java 命名规范 + +## 类命名 +- 使用 UpperCamelCase +- 示例：UserService, OrderController + +## 方法命名 +- 使用 lowerCamelCase +- 示例：getUserById, createOrder +... +--- +# Spring Boot 开发规范 + +## Controller 层 +- 使用 @RestController 注解 +- 返回统一响应格式 RestResult +... +``` + +## 记忆功能 + +本 Skill 会自动将加载的风格文件内容保存到记忆系统中，使得后续对话可以快速引用。 + +保存路径：`~/.claude/skills/load-codestyle/memory/codestyle-{language}.md` + +格式： +```markdown +--- +name: codestyle-{language} +description: {语言} 代码风格参考 +type: reference +language: {language} +--- + +{风格文件内容} +``` diff --git a/skills/load-codestyle/style/java/java-code-style.md b/skills/load-codestyle/style/java/java-code-style.md new file mode 100644 index 0000000..60abc65 --- /dev/null +++ b/skills/load-codestyle/style/java/java-code-style.md @@ -0,0 +1,338 @@ +# Java 代码风格规范 + +通用 Java 项目代码风格规范，适用于所有 Java 后端项目。 + +--- + +## 1. 项目结构 + +### 包组织 +- 基础包按公司域名倒写 + 项目名，如 `com.company.project` +- 按业务域划分模块，如 `user/`、`order/`、`product/` + +### 目录结构（各模块内） +``` +controller/ # 控制层 +service/ # 服务层接口 +service/impl/ # 服务层实现 +entity/ # 实体层 +entity/dto/ # 数据传输对象 +entity/vo/ # 视图对象 +mapper/ # 数据访问层（MyBatis/JPA） +manager/ # 复杂业务编排 +checker/ # 业务校验工具 +``` + +--- + +## 2. 命名规范 + +| 元素 | 规范 | 示例 | +|------|------|------| +| 类名 | PascalCase，2-41字符 | `UserService`、`OrderController` | +| 方法名 | camelCase，1-31字符 | `getUserById()`、`saveOrder()` | +| 变量名 | camelCase | `userId`、`orderList` | +| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` | +| 包名 | 全小写，dot分隔 | `com.company.project.common.util` | + +### 特定后缀/前缀 +- Service 接口：前缀 `I`，如 `IUserService` +- Service 实现：后缀 `Impl`，如 `UserServiceImpl` +- DTO：后缀 `Dto` 或 `DTO` +- VO：后缀 `VO` +- 查询参数对象：后缀 `Query` 或 `Criteria` +- 校验工具类：后缀 `Checker` 或 `Validator` +- Manager：后缀 `Manager`（复杂业务编排层） + +--- + +## 3. 代码格式 + +- **缩进**：4空格（禁止Tab） +- **行长度**：最大120-200字符 +- **花括号**：K&R风格（同一行开括号） +- **文件最大行数**：通常不超过2000行 +- **方法最大行数**：通常不超过150-300行 +- **参数数量**：最多7-9个（超出考虑封装为对象） +- **if嵌套深度**：最多3-4层（超出考虑提取方法） + +--- + +## 4. 注释规范 + +### 类级Javadoc +```java +/** + * 用户服务类 + * + *

提供用户注册、登录、信息管理等核心功能

+ * + * @author authorName + * @since 2024-01-01 + */ +``` + +### 方法级Javadoc +```java +/** + * 根据用户ID获取用户信息 + * + * @param userId 用户ID + * @return 用户信息，不存在返回null + * @author authorName + * @since 2024年1月1日 00:00:00 + */ +public User getUserById(String userId) { } +``` + +### 字段注释 +```java +/** 用户ID */ +private String userId; +``` + +### 行内注释 +- 注释放在代码上方或行尾 +- 复杂业务逻辑需注释说明 + +--- + +## 5. 异常处理 + +### 异常使用原则 +- 业务异常使用自定义异常（如 `BusinessException`） +- 参数校验异常使用 `IllegalArgumentException` 或专用校验异常 +- 系统异常使用 `RuntimeException` 包装 + +### 全局异常处理 +```java +@ControllerAdvice +@RestController +public class GlobalExceptionHandler { + @ExceptionHandler(BusinessException.class) + public Result handleBusinessException(BusinessException e) { + return Result.error(e.getCode(), e.getMessage()); + } +} +``` + +### 日志记录 +```java +log.info("用户登录成功，userId={}", userId); +log.warn("订单处理超时，orderId={}", orderId); +log.error("数据库连接失败", e); +``` + +--- + +## 6. 常用代码模式 + +### DTO/Request/Response +```java +@Data +@Accessors(chain = true) +public class UserDTO implements Serializable { + @NotBlank(message = "用户名不能为空") + private String username; + + @NotNull(message = "年龄不能为空") + @Min(value = 0, message = "年龄不能为负数") + private Integer age; +} +``` + +### Entity +```java +@Data +@Entity +@Table(name = "t_user") +public class User implements Serializable { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private String id; + + @Column(name = "username") + private String username; +} +``` + +### Service +```java +public interface IUserService { + User getUserById(String userId); +} + +@Service +@RequiredArgsConstructor +public class UserServiceImpl implements IUserService { + private final IUserMapper userMapper; + + @Override + public User getUserById(String userId) { + return userMapper.selectById(userId); + } +} +``` + +### Controller +```java +@RestController +@RequestMapping("/users") +@RequiredArgsConstructor +public class UserController { + private final IUserService userService; + + @GetMapping("/{id}") + public Result getUserById(@PathVariable String id) { + return Result.ok(userService.getUserById(id)); + } +} +``` + +### 校验工具 +```java +public class UserValidator { + public static List validate(UserDTO dto) { + List errors = new ArrayList<>(); + if (dto.getUsername() == null || dto.getUsername().isBlank()) { + errors.add("用户名不能为空"); + } + return errors; + } +} +``` + +### Enum +```java +@Getter +@AllArgsConstructor +public enum UserStatus { + ENABLE("启用", "enable"), + DISABLE("禁用", "disable"); + + private final String desc; + private final String code; + + public static UserStatus getByCode(String code) { + return Arrays.stream(values()) + .filter(e -> e.getCode().equals(code)) + .findFirst() + .orElse(null); + } +} +``` + +### 常量类 +```java +public interface UserConstants { + int DEFAULT_PAGE_SIZE = 10; + int MAX_PAGE_SIZE = 100; + String DEFAULT_STATUS = "enable"; +} +``` + +--- + +## 7. API设计规范 + +### HTTP方法约束 +**强制约束：只能使用 GET 和 POST 方法** + +| 操作 | 方法 | 路径 | +|------|------|------| +| 查询 | GET | `/users/{id}` | +| 列表 | GET | `/users?name={name}` | +| 新增 | POST | `/users` | +| 更新 | POST + `/update` | `/users/update` | +| 删除 | POST + `/remove` | `/users/remove` | +| 部分更新 | POST + `/patch` | `/users/patch` | + +> **说明**：禁止使用 PUT、DELETE、PATCH 等其他HTTP方法。所有非GET请求均使用POST方法，通过路径后缀区分操作类型。 + +### 统一响应格式 +公司基础框架提供 `RestResult` 统一响应格式： + +```java +return RestResult.ok(data); // 成功 +return RestResult.ok(); // 无返回值的成功 +return RestResult.error(ResultCode.DATA_NONE); // 错误（根据错误码） +return RestResult.error(ResultCode.BUSINESS_LOGIC_ERROR, "自定义错误信息"); +``` + +> **说明**：`RestResult` 是公司基础框架的核心组件，所有API响应必须使用该格式，不可自行定义其他响应格式。 + +### 统一响应格式 +```java +public class RestResult { + private int code; + private String message; + private T data; + + public static RestResult ok(T data) { } + public static RestResult error(String message) { } + public static RestResult error(int code, String message) { } +} +``` + +--- + +## 8. 事务处理 + +```java +@Transactional(rollbackFor = Exception.class) +public void saveUser(User user) { + userMapper.insert(user); + // 其他操作 +} +``` + +--- + +## 9. API文档注解 + +### Swagger/OpenAPI 3.0 +```java +@Api(tags = "用户管理") +@RestController +@RequestMapping("/users") +public class UserController { + @ApiOperation("根据ID获取用户") + @GetMapping("/{id}") + public RestResult getUser(@ApiParam("用户ID") @PathVariable String id) { } +} +``` + +### SpringDoc OpenAPI（推荐） +```java +@Tag(name = "用户管理", description = "用户相关接口") +@RestController +@RequestMapping("/users") +public class UserController { + @Operation(summary = "根据ID获取用户") + @GetMapping("/{id}") + public RestResult getUser(@Parameter(description = "用户ID") @PathVariable String id) { } +} +``` + +--- + +## 10. 禁止事项 + +- **禁止魔法数字**：使用常量替代，如 `MAX_RETRY_COUNT` +- **禁止无用的import**：保持代码整洁 +- **禁止长方法**：方法不超过150行，拆分为多个小方法 +- **禁止深度嵌套**：if嵌套不超过3-4层 +- **禁止硬编码**：配置信息放入配置文件 +- **禁止空指针**：使用 `Objects.requireNonNull()` 或 Optional +- **禁止swallow异常**：异常必须记录或重新抛出 + +--- + +## 11. 最佳实践 + +- 使用 Lombok 减少样板代码（`@Data`、`@Slf4j`、`@Service`） +- 使用 `@RequiredArgsConstructor` 代替构造器注入 +- 使用 Optional 处理可能为null的返回值 +- 使用 Stream API 处理集合操作 +- 接口方法参数不超过5个，超出使用DTO封装 +- 日志记录使用占位符 `{}` 而非字符串拼接