mini_tp/README_API.md

ThinkPHP 8 API 多应用脚手架

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

环境要求

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

目录结构

tp/
├── app/                   # 应用目录
│   ├── api/              # API 应用
│   │   ├── controller/   # 控制器
│   │   │   ├── BaseController.php  # 基础控制器
│   │   │   ├── Index.php           # 首页控制器
│   │   │   └── User.php            # 用户控制器
│   │   ├── model/        # 模型
│   │   ├── validate/     # 验证器
│   │   ├── middleware/   # 中间件
│   │   │   ├── Auth.php           # 认证中间件
│   │   │   └── CrossDomain.php    # 跨域中间件
│   │   ├── common/       # 公共类
│   │   │   └── Response.php       # 统一响应类
│   │   └── AppService.php # 应用服务
│   └── BaseController.php # 默认基础控制器
├── config/               # 配置文件
├── route/                # 路由
│   └── api.php          # API 路由配置
├── 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/index
• Method: GET
• 响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "name": "ThinkPHP API",
        "version": "8.1.3",
        "message": "Welcome to ThinkPHP API Application"
    },
    "time": 1640000000
}

2. 健康检查

• URL: /api/health
• Method: GET
• 响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "status": "ok",
        "timestamp": "2024-01-01 12:00:00"
    },
    "time": 1640000000
}

3. 用户登录

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

{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "example_token_xxx",
        "username": "demo"
    },
    "time": 1640000000
}

4. 用户注册

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

{
    "code": 200,
    "msg": "注册成功",
    "data": {
        "user_id": 1001
    },
    "time": 1640000000
}

认证接口（需要 token）

5. 获取用户信息

• URL: /api/user/info
• Method: GET
• Headers: token: your_token
• 响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1,
        "username": "demo_user",
        "nickname": "演示用户",
        "avatar": "",
        "email": "demo@example.com",
        "created_at": "2024-01-01 12:00:00"
    },
    "time": 1640000000
}

功能特性

1. 多应用模式

• 采用 ThinkPHP 多应用扩展
• 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',
]);

// 或使用验证器
$this->validate($data, 'app\api\validate\User.login');

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@Demo

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

# 生成验证器
php think make:validate api@Demo

扩展安装

# 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。