# api-mh

**Repository Path**: wwf1992_admin/api-mh

## Basic Information

- **Project Name**: api-mh
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-23
- **Last Updated**: 2025-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

ThinkPHP 6.0
===============

> 运行环境要求PHP7.2+，兼容PHP8.1

[官方应用服务市场](https://market.topthink.com) | [`ThinkAPI`——官方统一API服务](https://docs.topthink.com/think-api)

ThinkPHPV6.0版本由[亿速云](https://www.yisu.com/)独家赞助发布。

## 主要新特性

* 采用`PHP7`强类型（严格模式）
* 支持更多的`PSR`规范
* 原生多应用支持
* 更强大和易用的查询
* 全新的事件系统
* 模型事件和数据库事件统一纳入事件系统
* 模板引擎分离出核心
* 内部功能中间件化
* SESSION/Cookie机制改进
* 对Swoole以及协程支持改进
* 对IDE更加友好
* 统一和精简大量用法

## 安装

~~~
composer create-project topthink/think tp 6.0.*
~~~

如果需要更新框架使用
~~~
composer update topthink/framework
~~~

## 文档

[完全开发手册](https://www.kancloud.cn/manual/thinkphp6_0/content)

## 参与开发

请参阅 [ThinkPHP 核心框架包](https://github.com/top-think/framework)。

## 版权信息

ThinkPHP遵循Apache2开源协议发布，并提供免费使用。

本项目包含的第三方源码和二进制文件之版权信息另行标注。

版权所有Copyright © 2006-2021 by ThinkPHP (http://thinkphp.cn)

All rights reserved。

ThinkPHP® 商标和著作权所有者为上海顶想信息科技有限公司。

更多细节参阅 [LICENSE.txt](LICENSE.txt)

# ThinkPHP项目开发规范

## 目录结构规范
```
project  应用部署目录
├─app           应用目录
│  ├─controller      控制器目录
│  │  ├─api         API控制器目录
│  │  └─admin       后台控制器目录
│  ├─model          模型目录
│  ├─service        业务服务目录
│  ├─validate       验证器目录
│  └─middleware     中间件目录
├─config       配置目录
├─route        路由目录
├─runtime      运行时目录
├─public       WEB目录（对外访问目录）
└─vendor       Composer类库目录
```

## 命名规范

### 1. 目录和文件
- 目录使用小写+下划线
- 类库、类文件都以`.php`为后缀
- 类文件名均以命名空间定义，并且命名空间的路径和类库文件所在路径一致
- 类名和类文件名保持一致，采用驼峰法命名（首字母大写）

### 2. 类命名
- 控制器类：大驼峰命名，以`Controller`结尾，例如：`UserController`
- 模型类：大驼峰命名，例如：`User`、`UserType`
- 服务类：大驼峰命名，以`Service`结尾，例如：`UserService`
- 验证器类：大驼峰命名，以`Validate`结尾，例如：`UserValidate`

### 3. 方法命名
- 控制器方法：小驼峰命名，例如：`index`、`add`、`edit`、`delete`
- 模型方法：小驼峰命名，例如：`getUser`、`saveUser`
- 服务方法：小驼峰命名，例如：`createOrder`、`updateUserInfo`

### 4. 变量命名
- 普通变量：小驼峰命名，例如：`userName`、`orderList`
- 私有变量：小驼峰命名，前缀下划线，例如：`_config`、`_instance`
- 常量：大写下划线命名，例如：`APP_PATH`、`THINK_VERSION`

## API接口规范

### 1. 路由定义
```php
// 分组路由
Route::group('api/:version', function () {
    // 用户相关
    Route::group('user', function () {
        Route::post('login', 'api.User/login');
        Route::post('register', 'api.User/register');
    });
});
```

### 2. 返回数据格式
```php
return json([
    'code' => 0,                    // 状态码：0成功，非0失败
    'message' => 'success',         // 状态描述
    'data' => [                     // 数据主体
        'list' => [],
        'total' => 0
    ],
    'timestamp' => time()           // 时间戳
]);
```

### 3. 控制器规范
```php
namespace app\controller\api;

use app\BaseController;
use app\service\UserService;
use think\facade\Validate;

class UserController extends BaseController
{
    /**
     * @var UserService
     */
    protected $service;

    public function __construct(UserService $service)
    {
        parent::__construct();
        $this->service = $service;
    }

    /**
     * 获取用户信息
     */
    public function info()
    {
        // 参数验证
        $validate = Validate::rule([
            'id' => 'require|number'
        ]);
        
        if (!$validate->check($this->request->param())) {
            return $this->error($validate->getError());
        }

        // 业务处理
        $result = $this->service->getUserInfo($this->request->param('id'));
        
        // 返回结果
        return $this->success($result);
    }
}
```

### 4. 服务层规范
```php
namespace app\service;

use app\model\User;

class UserService
{
    /**
     * @var User
     */
    protected $model;

    public function __construct(User $model)
    {
        $this->model = $model;
    }

    /**
     * 获取用户信息
     * @param int $id
     * @return array
     */
    public function getUserInfo(int $id): array
    {
        return $this->model->where('id', $id)->find()->toArray();
    }
}
```

## 中间件规范

### 1. 权限验证中间件
```php
namespace app\middleware;

class Auth
{
    public function handle($request, \Closure $next)
    {
        // 权限验证逻辑
        if (!$this->checkToken()) {
            return json(['code' => 401, 'message' => '未授权']);
        }

        return $next($request);
    }

    protected function checkToken()
    {
        // Token验证逻辑
        return true;
    }
}
```

## 数据库规范

### 1. 表命名
- 使用小写字母，单词间使用下划线分隔
- 表名应该使用复数形式
- 表前缀使用项目的缩写，例如：`mh_users`

### 2. 字段命名
- 使用小写字母，单词间使用下划线分隔
- 必须包含的字段：`id`、`create_time`、`update_time`、`delete_time`（软删除）
- 布尔类型字段使用`is_`前缀，例如：`is_admin`、`is_delete`

### 3. 示例
```sql
CREATE TABLE `mh_users` (
    `id` int(11) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键',
    `username` varchar(32) NOT NULL DEFAULT '' COMMENT '用户名',
    `password` varchar(255) NOT NULL DEFAULT '' COMMENT '密码',
    `nickname` varchar(32) NOT NULL DEFAULT '' COMMENT '昵称',
    `avatar` varchar(255) NOT NULL DEFAULT '' COMMENT '头像',
    `is_admin` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否管理员',
    `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态：0禁用 1启用',
    `create_time` int(11) NOT NULL DEFAULT '0' COMMENT '创建时间',
    `update_time` int(11) NOT NULL DEFAULT '0' COMMENT '更新时间',
    `delete_time` int(11) DEFAULT NULL COMMENT '删除时间',
    PRIMARY KEY (`id`),
    KEY `idx_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
```

## 异常处理规范

### 1. 自定义异常类
```php
namespace app\exception;

class BusinessException extends \Exception
{
    public function __construct($message = "", $code = 0)
    {
        parent::__construct($message, $code);
    }
}
```

### 2. 异常处理
```php
try {
    // 业务逻辑
    throw new BusinessException('业务异常', 1001);
} catch (BusinessException $e) {
    return json([
        'code' => $e->getCode(),
        'message' => $e->getMessage()
    ]);
} catch (\Exception $e) {
    return json([
        'code' => 500,
        'message' => '服务器错误'
    ]);
}
```

## 注释规范 (Swagger/OpenAPI)

### 1. 控制器类注释
```php
/**
 * @OA\Info(
 *     title="项目名称 API",
 *     version="1.0.0",
 *     description="API接口文档"
 * )
 */
class UserController extends BaseController
{
}
```

### 2. 接口方法注释
```php
/**
 * @OA\Post(
 *     path="/api/user/login",
 *     tags={"用户管理"},
 *     summary="用户登录",
 *     description="用户登录接口",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(
 *             required={"username","password"},
 *             @OA\Property(property="username", type="string", example="admin", description="用户名"),
 *             @OA\Property(property="password", type="string", example="123456", description="密码")
 *         )
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="登录成功",
 *         @OA\JsonContent(
 *             @OA\Property(property="code", type="integer", example=0),
 *             @OA\Property(property="message", type="string", example="success"),
 *             @OA\Property(
 *                 property="data",
 *                 type="object",
 *                 @OA\Property(property="token", type="string", example="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."),
 *                 @OA\Property(property="user_info", type="object",
 *                     @OA\Property(property="id", type="integer", example=1),
 *                     @OA\Property(property="username", type="string", example="admin"),
 *                     @OA\Property(property="nickname", type="string", example="管理员")
 *                 )
 *             ),
 *             @OA\Property(property="timestamp", type="integer", example=1616745801)
 *         )
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="登录失败",
 *         @OA\JsonContent(
 *             @OA\Property(property="code", type="integer", example=1),
 *             @OA\Property(property="message", type="string", example="用户名或密码错误"),
 *             @OA\Property(property="data", type="object"),
 *             @OA\Property(property="timestamp", type="integer", example=1616745801)
 *         )
 *     )
 * )
 */
public function login()
{
    // 接口实现
}
```

### 3. 模型属性注释
```php
/**
 * @OA\Schema(
 *     schema="User",
 *     required={"id", "username", "password"},
 *     @OA\Property(property="id", type="integer", format="int64", description="用户ID"),
 *     @OA\Property(property="username", type="string", description="用户名"),
 *     @OA\Property(property="password", type="string", format="password", description="密码"),
 *     @OA\Property(property="nickname", type="string", description="昵称"),
 *     @OA\Property(property="avatar", type="string", format="url", description="头像"),
 *     @OA\Property(property="is_admin", type="boolean", description="是否管理员"),
 *     @OA\Property(property="status", type="integer", enum={0,1}, description="状态：0禁用 1启用"),
 *     @OA\Property(property="create_time", type="string", format="datetime", description="创建时间"),
 *     @OA\Property(property="update_time", type="string", format="datetime", description="更新时间")
 * )
 */
class User extends BaseModel
{
}
```

### 4. 通用响应体定义
```php
/**
 * @OA\Schema(
 *     schema="Response",
 *     required={"code", "message", "data", "timestamp"},
 *     @OA\Property(property="code", type="integer", example=0, description="状态码：0成功，非0失败"),
 *     @OA\Property(property="message", type="string", example="success", description="状态描述"),
 *     @OA\Property(property="data", type="object", description="数据主体"),
 *     @OA\Property(property="timestamp", type="integer", example=1616745801, description="时间戳")
 * )
 */
```

### 5. 分页响应定义
```php
/**
 * @OA\Schema(
 *     schema="PageResponse",
 *     required={"list", "total", "page", "limit"},
 *     @OA\Property(property="list", type="array", @OA\Items(ref="#/components/schemas/User")),
 *     @OA\Property(property="total", type="integer", description="总记录数"),
 *     @OA\Property(property="page", type="integer", description="当前页码"),
 *     @OA\Property(property="limit", type="integer", description="每页数量")
 * )
 */
```

### 6. 参数验证规则注释
```php
/**
 * @OA\Parameter(
 *     name="id",
 *     in="path",
 *     required=true,
 *     description="记录ID",
 *     @OA\Schema(type="integer")
 * )
 */
```

### 7. 生成API文档
在项目根目录创建swagger.php文件：
```php
<?php
require 'vendor/autoload.php';

$openapi = \OpenApi\Generator::scan(['app/controller']);
header('Content-Type: application/json');
echo $openapi->toJson();
```

访问方式：
1. 生成JSON文档：访问 http://your-domain/swagger.php
2. 使用Swagger UI查看：将JSON文档导入到 https://editor.swagger.io/

### 8. 接口分组示例
```php
/**
 * @OA\Tag(
 *     name="用户管理",
 *     description="用户相关接口"
 * )
 */
class UserController extends BaseController
{
    /**
     * @OA\Get(
     *     path="/api/user/list",
     *     tags={"用户管理"},
     *     summary="获取用户列表",
     *     @OA\Parameter(
     *         name="page",
     *         in="query",
     *         description="页码",
     *         required=false,
     *         @OA\Schema(type="integer", default=1)
     *     ),
     *     @OA\Parameter(
     *         name="limit",
     *         in="query",
     *         description="每页数量",
     *         required=false,
     *         @OA\Schema(type="integer", default=15)
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="获取成功",
     *         @OA\JsonContent(
     *             allOf={
     *                 @OA\Schema(ref="#/components/schemas/Response"),
     *                 @OA\Schema(
     *                     @OA\Property(
     *                         property="data",
     *                         ref="#/components/schemas/PageResponse"
     *                     )
     *                 )
     *             }
     *         )
     *     )
     * )
     */
    public function list()
    {
        // 接口实现
    }
}
```