feat: 添加 chinaweal-quicknote 和 load-codestyle 两个 skill
- 在 marketplace.json 中注册新 skill - 更新 README.md 说明文档
This commit is contained in:
parent
cb0004f684
commit
a4f8964de2
|
|
@ -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"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
22
README.md
22
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 插件市场安装（推荐）
|
||||
|
|
|
|||
|
|
@ -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 系统配置
|
||||
|
|
@ -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（示例文件已添加）
|
||||
- 可按需扩展其他语言
|
||||
|
|
@ -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}
|
||||
---
|
||||
|
||||
{风格文件内容}
|
||||
```
|
||||
|
|
@ -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
|
||||
/**
|
||||
* 用户服务类
|
||||
*
|
||||
* <p>提供用户注册、登录、信息管理等核心功能</p>
|
||||
*
|
||||
* @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<User> getUserById(@PathVariable String id) {
|
||||
return Result.ok(userService.getUserById(id));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 校验工具
|
||||
```java
|
||||
public class UserValidator {
|
||||
public static List<String> validate(UserDTO dto) {
|
||||
List<String> 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<T>` 统一响应格式：
|
||||
|
||||
```java
|
||||
return RestResult.ok(data); // 成功
|
||||
return RestResult.ok(); // 无返回值的成功
|
||||
return RestResult.error(ResultCode.DATA_NONE); // 错误（根据错误码）
|
||||
return RestResult.error(ResultCode.BUSINESS_LOGIC_ERROR, "自定义错误信息");
|
||||
```
|
||||
|
||||
> **说明**：`RestResult<T>` 是公司基础框架的核心组件，所有API响应必须使用该格式，不可自行定义其他响应格式。
|
||||
|
||||
### 统一响应格式
|
||||
```java
|
||||
public class RestResult<T> {
|
||||
private int code;
|
||||
private String message;
|
||||
private T data;
|
||||
|
||||
public static <T> RestResult<T> ok(T data) { }
|
||||
public static <T> RestResult<T> error(String message) { }
|
||||
public static <T> RestResult<T> 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<User> 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<User> 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封装
|
||||
- 日志记录使用占位符 `{}` 而非字符串拼接
|
||||
Loading…
Reference in New Issue