mini_tp/README_API.md

ThinkPHP 8 API 多应用脚手架

基于 ThinkPHP 8.1 的 API 接口开发脚手架，采用多应用模式。

环境要求

• PHP >= 8.0
• Composer
• MySQL >= 5.7

目录结构

tp/
├── app/
│   └── api/
│       ├── controller/
│       │   ├── BaseController.php
│       │   └── v1/
│       │       └── Auth.php
│       ├── model/
│       │   └── Member.php
│       ├── service/
│       │   └── AuthService.php
│       ├── middleware/
│       │   ├── Auth.php
│       │   └── CrossDomain.php
│       ├── common/
│       │   ├── Jwt.php
│       │   └── Response.php
│       ├── middleware.php
│       └── route/
│           └── app.php
├── config/               # 配置文件
├── public/               # 公共资源
├── runtime/              # 运行时目录
├── vendor/               # Composer 依赖
├── .env                  # 环境配置
├── database.sql          # 数据库结构
└── README.md            # 说明文档

安装步骤

1. 安装依赖

依赖已安装完成，如需更新：

composer install

2. 配置环境

复制 .env 文件并修改数据库配置：

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = tp_api
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8mb4

3. 创建数据库

CREATE DATABASE tp_api DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;

导入数据表结构：

mysql -u root -p tp_api < database.sql

4. 配置 Web 服务器

Nginx 配置示例

server {
    listen 80;
    server_name localhost;
    root /path/to/tp/public;
    index index.php index.html;

    location / {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php?s=/$1 last;
            break;
        }
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

5. 启动开发服务器

php think run

默认访问地址：http://localhost:8000

API 接口文档

公开接口

1. 用户登录

• URL: /api/v1/auth/login
• Method: POST
• 参数:
  • username: 用户名（必填）
  • password: 密码（必填）
• 响应示例:

{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "jwt_access_token",
        "refresh_token": "jwt_refresh_token",
        "expires_in": 604800,
        "user": {
            "userid": 1001,
            "username": "demo",
            "v_type": 0,
            "endtime": 0,
            "formtypeid": 0
        }
    },
    "time": 1640000000
}

2. 用户注册

• URL: /api/v1/auth/register
• Method: POST
• 参数:
  • username: 用户名（3-20位）
  • password: 密码（6-20位）
  • email: 邮箱
• 响应示例:

{
    "code": 200,
    "msg": "注册成功",
    "data": {
        "token": "jwt_access_token",
        "refresh_token": "jwt_refresh_token",
        "expires_in": 604800,
        "user": {
            "userid": 1001,
            "username": "demo",
            "v_type": 0,
            "endtime": 0,
            "formtypeid": 0
        }
    },
    "time": 1640000000
}

3. 刷新 Token

• URL: /api/v1/auth/refresh
• Method: POST
• 参数:
  • refresh_token: 刷新令牌

认证接口（需要 token）

4. 获取用户信息

• URL: /api/v1/auth/me
• Method: GET
• Headers: token: your_token
• 响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "userid": 1,
        "username": "demo_user",
        "v_type": 1,
        "endtime": 1777777777,
        "formtypeid": 0,
        "disabled": 0,
        "product": {
            "v_type": 1,
            "video_num": 100,
            "account_num": 5
        }
    },
    "time": 1640000000
}

5. 退出登录

• URL: /api/v1/auth/logout
• Method: POST
• Headers: token: your_token

6. 修改密码

• URL: /api/v1/auth/password
• Method: POST
• Headers: token: your_token
• 参数:
  • old_password: 原密码
  • new_password: 新密码
  • confirm_password: 确认新密码

功能特性

1. 多应用模式

• 采用 ThinkPHP 多应用扩展
• API 接口集中在 app/api
• 便于扩展其他应用模块

2. 统一响应格式

// 成功响应
return $this->success($data, '操作成功');

// 失败响应
return $this->error('操作失败', 400);

// 分页响应
return Response::paginate($list, $total, $page, $pageSize);

3. 中间件支持

• 跨域中间件: 支持 API 跨域请求
• 认证中间件: Token 验证（需自行实现具体逻辑）

4. 数据验证

// 控制器中使用
$this->validate($data, [
    'username' => 'require|length:3,20',
    'password' => 'require|length:6,20',
]);

5. 模型自动时间戳

protected $autoWriteTimestamp = true;

开发建议

1. 控制器开发

• 所有控制器继承 BaseController
• 使用 $this->success() 和 $this->error() 统一响应
• 复杂逻辑封装到 Service 层

2. 模型开发

• 使用模型关联处理表关系
• 定义访问器和修改器
• 使用自动时间戳

3. 异常处理

• 使用 try-catch 捕获异常
• 自定义异常处理类
• 记录错误日志

4. API 安全

• 使用 HTTPS
• Token 认证机制
• 参数签名验证
• 请求频率限制

5. 性能优化

• 开启路由缓存
• 使用缓存减少数据库查询
• 优化 SQL 查询
• 使用队列处理耗时任务

常用命令

# 启动开发服务器
php think run

# 清除缓存
php think clear

# 生成控制器
php think make:controller api@v1/Auth

# 生成模型
php think make:model api@Member

扩展安装

# JWT 认证
composer require firebase/php-jwt

# Redis 缓存
composer require topthink/think-cache

# 队列
composer require topthink/think-queue

# 定时任务
composer require topthink/think-cron

许可证

Apache 2.0

联系方式

如有问题请提交 Issue 或 PR。