vibe_coding/docs/guides/style-guide.md

📐 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)

导入顺序

// 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

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)

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always",
  "endOfLine": "lf",
  "plugins": ["prettier-plugin-tailwindcss"]
}

---

最后更新: 2026-02-24