139 lines
3.1 KiB
Markdown
139 lines
3.1 KiB
Markdown
# 📐 Code Style Guide
|
||
|
||
> 团队代码风格约定，AI 在生成代码时自动遵循
|
||
|
||
---
|
||
|
||
## 通用
|
||
|
||
- 缩进: 2 spaces (前端) / 4 spaces (PHP)
|
||
- 行宽: 100 chars (前端) / 120 chars (PHP)
|
||
- 行尾: LF
|
||
- 文件末尾: 空行
|
||
- 字符编码: UTF-8
|
||
|
||
---
|
||
|
||
## TypeScript / Vue 3 前端
|
||
|
||
- 分号: 使用 (`;`)
|
||
- 引号: 单引号 (`'`)
|
||
- 尾逗号: 无 (`trailing comma: none`)
|
||
- 箭头函数参数: 始终括号 (`(x) => x`)
|
||
|
||
### 导入顺序
|
||
|
||
```typescript
|
||
// 1. Vue 运行时和内置组合式
|
||
import { ref, computed, watch } from 'vue'
|
||
import { useRoute, useRouter } from 'vue-router'
|
||
|
||
// 2. 第三方库
|
||
// 管理端：import { ElMessage } from 'element-plus'
|
||
// 用户端：import { Dialog } from '@headlessui/vue'
|
||
import dayjs from 'dayjs'
|
||
|
||
// 3. 内部模块 (绝对路径)
|
||
import AppButton from '@/components/ui/AppButton.vue'
|
||
import { useUserStore } from '@/store/modules/user'
|
||
|
||
// 4. 相对路径
|
||
import { helper } from './utils'
|
||
|
||
// 5. JSDoc 类型引用（JS 项目无需 import type）
|
||
// @typedef {import('@/types').User} User
|
||
|
||
// 6. 样式
|
||
import './styles.css'
|
||
```
|
||
|
||
### 文件命名
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 组件 | PascalCase | `UserProfile.vue` |
|
||
| Composable | camelCase + use | `useAuth.ts` |
|
||
| 工具函数 | kebab-case | `format-date.ts` |
|
||
| 常量 | kebab-case | `api-routes.ts` |
|
||
| 类型文件 | kebab-case | `user.types.ts` |
|
||
| 测试 | 同源 + .test | `UserProfile.test.ts` |
|
||
| Store | camelCase | `user.ts` (in store/modules/) |
|
||
| 指令 | camelCase | `auth.ts` (in directives/) |
|
||
| API | camelCase | `production.ts` (in api/) |
|
||
|
||
---
|
||
|
||
## PHP 后端 (PSR-12)
|
||
|
||
- 分号: 必须
|
||
- 引号: 单引号优先，含变量用双引号
|
||
- 缩进: 4 spaces
|
||
- 行宽: 120 chars
|
||
- 大括号: 类/方法 `{` 换行，控制流 `{` 同行
|
||
|
||
### PHP 命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 类 | PascalCase | `OrderService` |
|
||
| 方法 | camelCase | `createOrder()` |
|
||
| 变量 | camelCase | `$orderData` |
|
||
| 常量 | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
|
||
| 数据库字段 | snake_case | `created_at` |
|
||
| 路由 | kebab-case 复数 | `/admin/production-orders` |
|
||
| 迁移文件 | snake_case 时间戳 | `2026_02_24_100000_create_orders_table.php` |
|
||
|
||
### PHP 文件结构
|
||
|
||
```php
|
||
<?php
|
||
|
||
declare(strict_types=1);
|
||
|
||
namespace App\Service\Production;
|
||
|
||
use App\Model\Production\ProductionOrder;
|
||
use App\Repository\Production\OrderRepository;
|
||
use Hyperf\Di\Annotation\Inject;
|
||
|
||
class OrderService
|
||
{
|
||
#[Inject]
|
||
protected OrderRepository $orderRepository;
|
||
|
||
public function create(array $data): ProductionOrder
|
||
{
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
### PHP 必须遵循
|
||
|
||
- `declare(strict_types=1);` — 所有 PHP 文件
|
||
- 类属性使用类型声明
|
||
- 方法参数和返回值使用类型声明
|
||
- 使用 PHPStan Level max 进行静态分析
|
||
- 使用 PHP CS Fixer 格式化代码
|
||
|
||
---
|
||
|
||
## Prettier 配置 (.prettierrc)
|
||
|
||
```json
|
||
{
|
||
"semi": true,
|
||
"singleQuote": true,
|
||
"trailingComma": "none",
|
||
"printWidth": 100,
|
||
"tabWidth": 2,
|
||
"arrowParens": "always",
|
||
"endOfLine": "lf",
|
||
"plugins": ["prettier-plugin-tailwindcss"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
*最后更新: 2026-02-24*
|