项目开发规范(AI 协作必读)
本文档是项目的唯一事实来源(Single Source of Truth)。每次让 AI 生成代码前,将本文档内容贴入提示词的【项目约束】部分。
一、技术栈约束
1.1 版本锁定
| 组件 |
版本 |
禁止事项 |
| PHP |
7.4 |
禁用 PHP 8 语法:match、命名参数、构造器属性提升、readonly、enum |
| MySQL |
5.7 |
禁用 MySQL 8 特性:窗口函数、CTE(WITH)、JSON_TABLE |
| UniApp |
Vue 2 语法 |
禁用 Vue 3:<script setup>、ref()、reactive()、computed() 导入式写法 |
| Redis |
6.x |
— |
| Nginx |
1.20+ |
— |
1.2 PHP 7.4 合规写法对照
| 场景 |
❌ 禁止(PHP 8) |
✅ 正确(PHP 7.4) |
| 类型声明 |
function foo(int $a) 可以 |
可以用,但不能用联合类型 int|string |
| 属性定义 |
class Foo { public int $bar; } |
class Foo { public $bar = 0; } |
| 匹配表达式 |
$result = match($x) { 1 => 'a' } |
switch ($x) { case 1: $result = 'a'; break; } |
| 命名参数 |
foo(name: 'bar') |
foo('bar') |
| Null 安全运算符 |
$obj?->method() |
isset($obj) ? $obj->method() : null |
二、架构规范
2.1 分层架构
Controller(控制器)
│ 职责:接收参数、参数校验、调用 Service、返回响应
│ 禁止:直接操作数据库、写业务逻辑
▼
Service(业务逻辑层)
│ 职责:核心业务逻辑、事务控制、调用 Model
│ 禁止:直接输出 JSON、处理 HTTP 参数
▼
Model(数据访问层)
│ 职责:数据库增删改查、缓存读写
│ 禁止:包含业务判断逻辑
2.2 目录结构约定
app/
├── controller/
│ ├── api/ # 前端 API 接口
│ └── admin/ # 后台管理接口
├── service/ # 业务逻辑
├── model/ # 数据模型
├── middleware/ # 中间件
├── common/ # 公共函数
└── config/ # 配置文件
三、代码规范
3.1 命名规范
| 类型 |
规范 |
示例 |
| 数据库表名 |
蛇形小写,复数或单数统一 |
user、product、order_item |
| 数据库字段 |
蛇形小写 |
user_id、create_time |
| PHP 变量 |
驼峰 |
$orderNo、$userId |
| PHP 类名 |
大驼峰 |
OrderService、ProductModel |
| PHP 方法名 |
小驼峰 |
createOrder()、getUserInfo() |
| API 路径 |
蛇形小写或 RESTful |
/api/v1/products 或 /api/v1/order_list |
| UniApp 页面路径 |
蛇形小写 |
/pages/order_detail/order_detail |
3.2 PHP 代码规范
<?php
class OrderService
{
public function createOrder(array $data): string
{
$productId = (int)$data['product_id'];
$quantity = (int)($data['quantity'] ?? 1);
if ($productId <= 0 || $quantity <= 0) {
throw new BusinessException(1001, '参数错误');
}
$product = (new ProductModel())->findById($productId);
if (!$product) {
throw new BusinessException(2001, '商品不存在');
}
$amount = bcmul($product['price'], $quantity, 2);
return $orderNo;
}
}
function create($data) {
$id = $data['id'];
$sql = "SELECT * FROM product WHERE id=" . $id;
return json(['code'=>0,'data'=>$sql]);
}
3.3 UniApp 前端规范
import { request } from '@/api/request.js'
export function getOrderList(params) {
return request({ url: '/orders', method: 'GET', data: params })
}
export default {
data() {
return { list: [] }
},
methods: {
async loadData() {
const data = await getOrderList({ page: 1 })
this.list = data.list
}
}
}
四、数据库规范
4.1 建表规范
| 规则 |
说明 |
| 引擎 |
统一 InnoDB |
| 字符集 |
统一 utf8mb4、utf8mb4_unicode_ci |
| 主键 |
每张表必须有 id BIGINT UNSIGNED AUTO_INCREMENT |
| 时间字段 |
create_time、update_time 用 INT UNSIGNED 存时间戳 |
| 软删除 |
delete_time 字段,NULL 表示未删除 |
| 金额字段 |
DECIMAL(10,2),禁止用 FLOAT/DOUBLE |
| 状态字段 |
TINYINT,注释标明各值含义 |
| 布尔字段 |
TINYINT(1),0/1 |
| 外键字段 |
命名为 xxx_id,如 user_id |
| 字段注释 |
每个字段必须有 COMMENT |
4.2 建表模板
CREATE TABLE `表名` (
`id` int unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
`字段名` 类型 NOT NULL DEFAULT '默认值' COMMENT '字段说明',
`status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1正常 0禁用',
`create_time` int unsigned NOT NULL COMMENT '创建时间',
`update_time` int unsigned NOT NULL COMMENT '更新时间',
`delete_time` int unsigned DEFAULT NULL COMMENT '删除时间',
PRIMARY KEY (`id`),
KEY `idx_字段名` (`字段名`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='表说明';
4.3 索引规范
| 规则 |
说明 |
| 索引命名 |
普通索引 idx_字段名,唯一索引 uk_字段名 |
| 联合索引 |
按查询频率从高到低排列字段 |
| 禁止 |
单表索引超过 5 个;大文本字段建索引 |
| 必须加索引 |
WHERE 条件字段、JOIN 关联字段、ORDER BY 排序字段 |
五、API 规范
5.1 统一响应格式
{ "code": 0, "msg": "success", "data": {} }
{ "code": 1001, "msg": "参数错误", "data": null }
{
"code": 0,
"msg": "success",
"data": {
"list": [],
"total": 100,
"page": 1,
"page_size": 20
}
}
5.2 状态码约定
| 范围 |
含义 |
| 0 |
成功 |
| 1xxx |
参数/校验错误 |
| 2xxx |
业务逻辑错误(如库存不足) |
| 3xxx |
权限错误(未登录、无权限) |
| 4xxx |
限流/安全拦截 |
| 5xxx |
服务端异常 |
5.3 接口规范
| 规则 |
说明 |
| 路径前缀 |
/api/v1/ |
| 认证方式 |
Header: Authorization: Bearer {token} |
| 分页参数 |
page(页码)+ page_size(每页条数,默认 20,最大 100) |
| 时间格式 |
统一用时间戳(秒),前端格式化展示 |
| 列表字段 |
列表接口只返回必要字段,不返回完整详情 |
六、安全规范
| 安全项 |
约束 |
| SQL 注入 |
全部用预处理语句或查询构造器,禁止字符串拼接 SQL |
| XSS |
输出转义 htmlspecialchars();前端用 v-text 不用 v-html |
| 密码存储 |
password_hash() 加密,禁止 MD5/SHA1 |
| Token |
JWT 签发,密钥从环境变量读取,不硬编码 |
| 文件上传 |
校验 MIME + 后缀白名单 + 重命名 + 存储到非 Web 目录 |
| 接口限流 |
每用户每分钟最多 60 次请求(Redis 滑动窗口) |
| 越权防护 |
每个接口校验当前用户是否有权操作目标资源 |
| 敏感配置 |
数据库密码、API Key、JWT 密钥写入 .env,不入 Git |
| HTTPS |
全站 HTTPS,禁止 HTTP 传输敏感数据 |
七、版本控制规范
7.1 Git 提交规范
<类型>: <简短描述>
类型:
feat 新功能
fix 修复 Bug
refactor 重构(不改功能)
docs 文档变更
style 代码格式(不改逻辑)
perf 性能优化
chore 构建/工具变更
示例:
feat: 新增商品列表接口
fix: 修复订单金额计算精度问题
refactor: 重构用户登录逻辑
7.2 分支规范
| 分支 |
用途 |
master |
生产环境,只合并经过测试的代码 |
dev |
开发主分支 |
feature/xxx |
功能开发分支 |
fix/xxx |
Bug 修复分支 |
7.3 .gitignore 必须包含
.env
/vendor/
/runtime/
/node_modules/
/unpackage/dist/
*.log
八、性能约束
| 圄景 |
约束 |
| 接口响应时间 |
普通接口 < 200ms,复杂查询 < 500ms |
| 数据库查询 |
单接口 SQL 查询不超过 5 条,禁止 N+1 查询 |
| 分页大小 |
每页最多 100 条,默认 20 条 |
| 缓存 TTL |
详情页 1 小时,列表页 5 分钟,配置类 24 小时 |
| 图片大小 |
单张不超过 500KB,列表缩略图不超过 100KB |
| Redis 使用 |
读取后及时释放连接,禁止在循环中频繁读写 |
九、AI 协作提示词模板
每次让 AI 写代码时,复制以下模板并填充具体任务:
你是一位资深开发工程师,帮我实现以下功能。
【项目约束】
- 技术栈:PHP 7.4 + MySQL 5.7 + UniApp(Vue 2)+ Redis 6
- 禁用 PHP 8 语法、MySQL 8 特性、Vue 3 语法
- 三层架构:Controller → Service → Model
- SQL 用预处理,禁止拼接
- 响应格式:{"code":0,"msg":"","data":{}}
- 金额用 bcmath,时间用时间戳
【已有表结构】
[粘贴相关表结构]
【功能需求】
[描述具体功能]
【输出要求】
- 生成完整可运行代码
- 关键逻辑加注释
- 标注需要手动配置的部分
使用方式:本文件是项目的唯一规范来源。新增约束时更新本文件,并在每次 AI 对话时将相关章节贴入提示词。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
评论(0)