mirror of
https://github.com/Lydanne/spaceflow.git
synced 2026-03-11 19:52:45 +08:00
216 lines
4.5 KiB
Markdown
216 lines
4.5 KiB
Markdown
# Review Spec 规范
|
||
|
||
Review Spec 是 Spaceflow 中用于定义代码审查规则的 Markdown 格式文档。AI 审查系统会读取这些规范，并据此对代码进行自动化审查。
|
||
|
||
## 文件命名规则
|
||
|
||
规范文件名必须遵循以下格式：
|
||
|
||
```text
|
||
<扩展名>.<类型>.md
|
||
```
|
||
|
||
| 部分 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| 扩展名 | 适用的文件扩展名，多个用 `&` 连接 | `js&ts`, `vue`, `tsx` |
|
||
| 类型 | 规范类型，可多级，用 `.` 分隔 | `nest`, `test-code`, `file-name` |
|
||
| 后缀 | 必须是 `.md` | `.md` |
|
||
|
||
示例：
|
||
|
||
```text
|
||
js&ts.nest.md # JS/TS NestJS 项目规范
|
||
js&ts.file-name.md # JS/TS 文件命名规范
|
||
js&ts.test-code.md # JS/TS 测试代码规范
|
||
vue.base.md # Vue 基础规范
|
||
```
|
||
|
||
## 文件结构
|
||
|
||
### 文件级配置
|
||
|
||
位于文件开头，使用 blockquote 语法：
|
||
|
||
```markdown
|
||
> - includes `*.controller.ts` `*.service.ts`
|
||
> - severity `warn`
|
||
> - override `[JsTs.FileName]`
|
||
```
|
||
|
||
### 规则定义
|
||
|
||
使用二级标题定义规则：
|
||
|
||
````markdown
|
||
## 规则标题 `[规则ID]`
|
||
|
||
规则描述...
|
||
|
||
### Good
|
||
|
||
```typescript
|
||
// 推荐代码示例
|
||
```
|
||
|
||
### Bad
|
||
|
||
```typescript
|
||
// 不推荐代码示例
|
||
```
|
||
````
|
||
|
||
## 文件级配置项
|
||
|
||
### `includes`
|
||
|
||
指定规范适用的文件路径模式（glob）。
|
||
|
||
```markdown
|
||
> - includes `**/*.controller.ts` `**/*.service.ts`
|
||
```
|
||
|
||
- 支持 `*`（任意字符）和 `**`（任意层级）
|
||
- 多个模式用空格分隔，包裹在反引号中
|
||
|
||
### `severity`
|
||
|
||
指定规则的默认严重程度。
|
||
|
||
```markdown
|
||
> - severity `warn`
|
||
```
|
||
|
||
| 值 | 含义 | 显示 | 阻止合并 |
|
||
|----|------|------|----------|
|
||
| `error` | 错误 | 🔴 红色 | 通常阻止 |
|
||
| `warn` | 警告 | 🟡 黄色 | 通常不阻止 |
|
||
| `off` | 关闭 | 不显示 | 否 |
|
||
|
||
### `override`
|
||
|
||
排除其他规范文件中的规则，支持前缀匹配。
|
||
|
||
```markdown
|
||
> - override `[JsTs.FileName]`
|
||
```
|
||
|
||
排除所有以 `JsTs.FileName` 开头的规则（包括 `JsTs.FileName.UpperCamel` 等子规则）。
|
||
|
||
## 规则级配置
|
||
|
||
可以在规则内容中使用 blockquote 覆盖文件级配置：
|
||
|
||
```markdown
|
||
## 服务规范 `[JsTs.Nest.Service]`
|
||
|
||
服务文件包含业务逻辑...
|
||
|
||
> - severity `warn`
|
||
```
|
||
|
||
## 规则 ID 命名
|
||
|
||
规则 ID 支持多级命名，使用 `.` 分隔：
|
||
|
||
```markdown
|
||
## 主规则 `[JsTs.Nest]`
|
||
## 控制器规范 `[JsTs.Nest.Controller]`
|
||
## 服务规范 `[JsTs.Nest.Service]`
|
||
```
|
||
|
||
## 远程规范仓库
|
||
|
||
支持从 Git 仓库加载规范文件：
|
||
|
||
```json
|
||
{
|
||
"review": {
|
||
"references": [
|
||
"./references",
|
||
"https://github.com/your-org/review-spec"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 支持的 URL 格式
|
||
|
||
| 格式 | 示例 |
|
||
|------|------|
|
||
| GitHub 仓库 | `https://github.com/org/repo` |
|
||
| GitHub 目录 | `https://github.com/org/repo/tree/main/references` |
|
||
| Gitea 仓库 | `https://git.example.com/org/repo` |
|
||
| Gitea 目录 | `https://git.example.com/org/repo/src/branch/main/references` |
|
||
| SSH | `git@host:owner/repo.git` |
|
||
| SSH（完整） | `git+ssh://git@host/owner/repo.git` |
|
||
|
||
远程规范会缓存到 `~/.spaceflow/review-spec-cache/`，TTL 为 5 分钟（CI 环境中每次拉取最新）。
|
||
|
||
## 完整示例
|
||
|
||
````markdown
|
||
# NestJS 项目规范 `[JsTs.Nest]`
|
||
|
||
> - includes `*.controller.ts` `*.service.ts` `*.module.ts`
|
||
> - severity `error`
|
||
> - override `[JsTs.FileName]`
|
||
|
||
## 控制器规范 `[JsTs.Nest.Controller]`
|
||
|
||
控制器文件不能包含业务逻辑，只能调用 service 方法。
|
||
|
||
### Good
|
||
|
||
```typescript
|
||
@Controller("user")
|
||
export class UserController {
|
||
constructor(private readonly userService: UserService) {}
|
||
|
||
@Get()
|
||
async getUser(@Param("id") id: string) {
|
||
return this.userService.findById(id);
|
||
}
|
||
}
|
||
```
|
||
|
||
### Bad
|
||
|
||
```typescript
|
||
@Controller("user")
|
||
export class UserController {
|
||
@Get()
|
||
async getUser(@Param("id") id: string) {
|
||
const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
|
||
return user;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 服务规范 `[JsTs.Nest.Service]`
|
||
|
||
服务文件包含业务逻辑，必须通过 model 访问数据库。
|
||
|
||
> - severity `warn`
|
||
|
||
### Good
|
||
|
||
```typescript
|
||
@Injectable()
|
||
export class UserService {
|
||
constructor(private readonly userModel: UserModel) {}
|
||
|
||
async getUser(id: string) {
|
||
return this.userModel.findById(id);
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
## 最佳实践
|
||
|
||
- **规则 ID 命名** — 使用有意义的层级结构，如 `语言.类型.规则名`
|
||
- **代码示例** — 提供清晰的 Good/Bad 示例
|
||
- **严重程度** — 合理设置 severity，避免过多 error 阻塞开发
|
||
- **文件组织** — 按功能或类型组织规则文件，避免单个文件过大
|
||
- **includes 精确** — 使用精确的文件路径匹配，避免误匹配
|