编码规则

1. 命名规范

1.1 目录和文件命名

目录名：使用小写字母，单词之间用下划线分隔（snake_case）
```
app/adminapi/controller/sys/
app/model/pay/
```
文件名：使用小写字母，单词之间用下划线分隔（snake_case）
```
user.php
pay_channel.php
```
类文件名：使用驼峰命名法（PascalCase），与类名保持一致
```
User.php
PayChannel.php
```

1.2 类和方法命名

类名：使用大驼峰命名法（PascalCase）
php
```
class UserController
class PayService
```

方法名：使用小驼峰命名法（camelCase）

php

public function getUserList()
private function processPayment()

私有方法：以双下划线开头（__privateMethod）
php
```
private function __generateToken()
```

1.3 变量命名

普通变量：使用小驼峰命名法（camelCase）
php
```
$userId
$paymentAmount
```
常量：使用大写字母，单词之间用下划线分隔（SNAKE_CASE）
php
```
const MAX_PAGE_SIZE = 100;
define('API_VERSION', '1.0');
```
配置参数：使用小写字母，单词之间用下划线分隔（snake_case）
php
```
'app_id' => 'your_app_id',
'api_key' => 'your_api_key',
```

2. 代码风格

2.1 缩进和换行

使用4个空格进行缩进（不使用制表符）
每行代码长度不超过120个字符
大括号使用"K&R"风格，即左大括号与语句同一行，右大括号单独一行
php
```
if ($condition) {
    // 代码块
} else {
    // 代码块
}
```

2.2 注释规范

类注释：使用PHPDoc格式，包含类的描述、作者、创建时间等信息

php

/**
 * 用户控制器
 * @author Niucloud Team
 * @since 2026-04-02
 */
class UserController

方法注释：使用PHPDoc格式，包含方法描述、参数、返回值等信息

php

/**
 * 获取用户列表
 * @param array $params 查询参数
 * @return array 用户列表
 */
public function getUserList($params)

行内注释：使用//开头，注释内容与代码保持适当距离
php
```
$userId = 1; // 用户ID
```

2.3 空格使用

操作符两侧使用空格
php
```
$result = $a + $b;
```
逗号后使用空格
php
```
function($param1, $param2)
```
括号内不使用空格
php
```
if ($condition)
```
函数参数之间使用空格
php
```
function($param1, $param2)
```

3. 代码结构

3.1 类结构

类的成员变量放在类的开头
构造函数和析构函数放在成员变量之后
公共方法放在私有方法之前

静态方法放在实例方法之前

php

class User {
    private $id;
    private $name;
    
    public function __construct($id, $name) {
        $this->id = $id;
        $this->name = $name;
    }
    
    public static function create($data) {
        // 创建用户
    }
    
    public function getName() {
        return $this->name;
    }
    
    private function __validateData($data) {
        // 验证数据
    }
}

3.2 文件结构

每个文件只包含一个类
文件开头使用命名空间声明
导入必要的类和函数

类定义后使用适当的空白行分隔不同的方法

php

namespace app\adminapi\controller\user;

use think\Controller;
use app\model\sys\SysUser;

class UserController extends Controller {
    // 方法定义
}

4. 错误处理

4.1 异常处理

使用try-catch块捕获异常
异常信息要清晰明确
记录异常日志
php

try { // 可能抛出异常的代码 } catch (Exception $e) { // 记录日志 log_error($e->getMessage()); // 返回错误信息 return json(['code' => 500, 'message' => '操作失败']); }


### 4.2 错误返回
- API接口返回统一的错误格式
- 错误码和错误信息要一致
- 对用户友好的错误提示
```php
// 成功返回
return json(['code' => 200, 'message' => 'success', 'data' => $data]);

// 错误返回
return json(['code' => 400, 'message' => '参数错误']);

5. 安全规范

5.1 输入验证

对所有用户输入进行验证
使用框架的验证机制

防止SQL注入、XSS攻击等安全问题

php

// 使用验证器
$validate = validate('User');
if (!$validate->check($data)) {
    return json(['code' => 400, 'message' => $validate->getError()]);
}

5.2 权限控制

实现基于角色的权限控制
验证用户权限

防止越权访问

php

// 检查权限
if (!$this->checkPermission('user:edit')) {
    return json(['code' => 403, 'message' => '无权限操作']);
}

6. 性能优化

6.1 数据库优化

使用索引
避免全表扫描

合理使用缓存

php

// 使用索引查询
$user = Db::name('user')->where('id', $id)->find();

// 使用缓存
$cacheKey = 'user_' . $id;
$user = cache($cacheKey);
if (!$user) {
    $user = Db::name('user')->where('id', $id)->find();
    cache($cacheKey, $user, 3600);
}

6.2 代码优化

减少重复代码
优化循环和条件判断

使用适当的数据结构

php

// 优化前
for ($i = 0; $i < count($users); $i++) {
    // 处理每个用户
}

// 优化后
$count = count($users);
for ($i = 0; $i < $count; $i++) {
    // 处理每个用户
}

7. 版本控制

7.1 Git规范

提交信息要清晰明确
分支管理要规范

定期合并代码

# 提交信息格式
feat: 添加新功能
fix: 修复bug
docs: 更新文档
style: 代码风格调整
refactor: 代码重构
test: 测试相关
chore: 构建或依赖更新

7.2 代码审查

定期进行代码审查
遵循代码规范
确保代码质量

8. 代码示例

8.1 控制器示例

php

<?php
namespace app\adminapi\controller\user;

use app\adminapi\controller\BaseController;
use app\model\sys\SysUser;
use app\validate\sys\UserValidate;

/**
 * 用户控制器
 */
class UserController extends BaseController {
    /**
     * 获取用户列表
     */
    public function lists() {
        $params = $this->request->param();
        $userModel = new SysUser();
        $list = $userModel->getUserList($params);
        return success($list);
    }
    
    /**
     * 添加用户
     */
    public function add() {
        $data = $this->request->param();
        $validate = new UserValidate();
        if (!$validate->check($data)) {
            return error($validate->getError());
        }
        $userModel = new SysUser();
        $result = $userModel->addUser($data);
        return success($result);
    }
    
    /**
     * 编辑用户
     */
    public function edit($id) {
        $data = $this->request->param();
        $validate = new UserValidate();
        if (!$validate->check($data)) {
            return error($validate->getError());
        }
        $userModel = new SysUser();
        $result = $userModel->editUser($id, $data);
        return success($result);
    }
    
    /**
     * 删除用户
     */
    public function del($id) {
        $userModel = new SysUser();
        $result = $userModel->delUser($id);
        return success($result);
    }
}

8.2 模型示例

php

<?php
namespace app\model\sys;

use think\Model;

/**
 * 用户模型
 */
class SysUser extends Model {
    protected $name = 'sys_user';
    
    /**
     * 获取用户列表
     */
    public function getUserList($params) {
        $page = $params['page'] ?? 1;
        $limit = $params['limit'] ?? 10;
        
        $query = $this->field('id, username, nickname, email, phone, status, create_time');
        
        if (!empty($params['username'])) {
            $query->where('username', 'like', '%' . $params['username'] . '%');
        }
        
        if (isset($params['status'])) {
            $query->where('status', $params['status']);
        }
        
        $list = $query->paginate([
            'page' => $page,
            'list_rows' => $limit
        ]);
        
        return $list;
    }
    
    /**
     * 添加用户
     */
    public function addUser($data) {
        // 加密密码
        $data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
        $data['create_time'] = time();
        $data['update_time'] = time();
        
        return $this->save($data);
    }
    
    /**
     * 编辑用户
     */
    public function editUser($id, $data) {
        if (!empty($data['password'])) {
            $data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
        }
        $data['update_time'] = time();
        
        return $this->where('id', $id)->update($data);
    }
    
    /**
     * 删除用户
     */
    public function delUser($id) {
        return $this->where('id', $id)->delete();
    }
}

8.3 验证器示例

php

<?php
namespace app\validate\sys;

use think\Validate;

/**
 * 用户验证器
 */
class UserValidate extends Validate {
    protected $rule = [
        'username' => 'require|length:2,20',
        'password' => 'require|length:6,20',
        'email' => 'email',
        'phone' => 'mobile',
        'status' => 'in:0,1'
    ];
    
    protected $message = [
        'username.require' => '用户名不能为空',
        'username.length' => '用户名长度在2-20之间',
        'password.require' => '密码不能为空',
        'password.length' => '密码长度在6-20之间',
        'email.email' => '邮箱格式不正确',
        'phone.mobile' => '手机号格式不正确',
        'status.in' => '状态值不正确'
    ];
    
    protected $scene = [
        'add' => ['username', 'password', 'email', 'phone', 'status'],
        'edit' => ['email', 'phone', 'status']
    ];
}

系统部署

后台手册

前端手册

Admin 端

UniApp 端

模块开发

附录

编码规则

1. 命名规范

1.1 目录和文件命名

1.2 类和方法命名

1.3 变量命名

2. 代码风格

2.1 缩进和换行

2.2 注释规范

2.3 空格使用

3. 代码结构

3.1 类结构

3.2 文件结构

4. 错误处理

4.1 异常处理

5. 安全规范

5.1 输入验证

5.2 权限控制

6. 性能优化

6.1 数据库优化

6.2 代码优化

7. 版本控制

7.1 Git规范

7.2 代码审查

8. 代码示例

8.1 控制器示例

8.2 模型示例

8.3 验证器示例

Admin 端

UniApp 端

编码规则 ​

1. 命名规范 ​

1.1 目录和文件命名 ​

1.2 类和方法命名 ​

1.3 变量命名 ​

2. 代码风格 ​

2.1 缩进和换行 ​

2.2 注释规范 ​

2.3 空格使用 ​

3. 代码结构 ​

3.1 类结构 ​

3.2 文件结构 ​

4. 错误处理 ​

4.1 异常处理 ​

5. 安全规范 ​

5.1 输入验证 ​

5.2 权限控制 ​

6. 性能优化 ​

6.1 数据库优化 ​

6.2 代码优化 ​

7. 版本控制 ​

7.1 Git规范 ​

7.2 代码审查 ​

8. 代码示例 ​

8.1 控制器示例 ​

8.2 模型示例 ​

8.3 验证器示例 ​

编码规则

1. 命名规范

1.1 目录和文件命名

1.2 类和方法命名

1.3 变量命名

2. 代码风格

2.1 缩进和换行

2.2 注释规范

2.3 空格使用

3. 代码结构

3.1 类结构

3.2 文件结构

4. 错误处理

4.1 异常处理

5. 安全规范

5.1 输入验证

5.2 权限控制

6. 性能优化

6.1 数据库优化

6.2 代码优化

7. 版本控制

7.1 Git规范

7.2 代码审查

8. 代码示例

8.1 控制器示例

8.2 模型示例

8.3 验证器示例