87 lines
2.2 KiB
Markdown
87 lines
2.2 KiB
Markdown
# 编码规范
|
||
|
||
## 1. 命名习惯
|
||
|
||
- **前端组件**: PascalCase (如 `ProjectCard.tsx`)。
|
||
- **后端文件**: kebab-case (如 `route-scanner.ts`)。
|
||
- **DTO**: 文件名为 `dto.ts`，类名为 `XxxDTO`。
|
||
|
||
## 2. 代码组织
|
||
|
||
web 项目代码组织如下：
|
||
|
||
```yaml
|
||
├── web/
|
||
│ ├── pages/
|
||
│ │ ├── components/ # 页面组件
|
||
│ │ ├── index.tsx # 页面入口组件
|
||
│ │ ├── service.ts # 当前页面使用到的 api 请求方法和纯函数
|
||
│ │ ├── types.ts # 当前页面使用到的类型定义
|
||
│ │ └── ...
|
||
│ └── hooks/ # 通用 hooks （不止一个组件引用）
|
||
│ └── stores/ # 全局状态
|
||
│ └── utils/ # 通用工具类
|
||
│ └── styles/ # 全局样式
|
||
│ └── assets/ # 静态资源
|
||
│ └── components/ # 通用组件
|
||
│ └── types/ # 全局类型定义
|
||
│ └── ...
|
||
```
|
||
|
||
## 3. 代码规范
|
||
|
||
- 注释符合 jsdoc 规范
|
||
- 代码简洁，避免冗余，移除无用的代码引用、变量、函数和css样式
|
||
- 禁止使用 any 类型
|
||
|
||
## 4. 前端发送net请求示例
|
||
|
||
- 分页
|
||
|
||
```typescript
|
||
import {net} from '@utils';
|
||
import type {APIPagination} from '@utils/net';
|
||
|
||
const data = await net.request<APIPagination<Deployment>>({
|
||
method: 'GET',
|
||
url: '/api/deployments',
|
||
// 注意：查询参数使用 params 传递，不要手动拼接到 url 上
|
||
params: {
|
||
projectId: 1,
|
||
page: 1,
|
||
pageSize: 10,
|
||
},
|
||
})
|
||
```
|
||
|
||
- 其他
|
||
|
||
```typescript
|
||
import {net} from '@utils';
|
||
|
||
const data = await net.request<void>({
|
||
method: 'POST',
|
||
url: '/api/deployment',
|
||
data: {
|
||
name: 'xxx',
|
||
description: 'xxx',
|
||
repository: 'https://a.com',
|
||
}
|
||
})
|
||
if (data.code === 0) {
|
||
console.log("创建成功")
|
||
} else {
|
||
console.log("创建失败")
|
||
}
|
||
```
|
||
|
||
## 5. 异步处理
|
||
|
||
- 统一使用 `async/await`。
|
||
- 后端错误通过抛出异常由 `exception.ts` 中间件统一捕获。
|
||
|
||
## 6. 格式化
|
||
|
||
- 使用 Biome 进行 Lint 和 Format。
|
||
- 提交代码前建议运行 `pnpm --filter web format`。
|