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. 安装依赖

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

```bash
composer install
```

### 2. 配置环境

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

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

### 3. 创建数据库

```sql
CREATE DATABASE tp_api DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
```

导入数据表结构：

```bash
mysql -u root -p tp_api < database.sql
```

### 4. 配置 Web 服务器

#### Nginx 配置示例

```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. 启动开发服务器

```bash
php think run
```

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

## API 接口文档

### 公开接口

#### 1. 用户登录
- **URL**: `/api/v1/auth/login`
- **Method**: POST
- **参数**:
  - `username`: 用户名（必填）
  - `password`: 密码（必填）
- **响应示例**:
```json
{
    "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`: 邮箱
- **响应示例**:
```json
{
    "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`
- **响应示例**:
```json
{
    "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. 统一响应格式
```php
// 成功响应
return $this->success($data, '操作成功');

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

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

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

### 4. 数据验证
```php
// 控制器中使用
$this->validate($data, [
    'username' => 'require|length:3,20',
    'password' => 'require|length:6,20',
]);
```

### 5. 模型自动时间戳
```php
protected $autoWriteTimestamp = true;
```

## 开发建议

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

### 2. 模型开发
- 使用模型关联处理表关系
- 定义访问器和修改器
- 使用自动时间戳

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

### 4. API 安全
- 使用 HTTPS
- Token 认证机制
- 参数签名验证
- 请求频率限制

### 5. 性能优化
- 开启路由缓存
- 使用缓存减少数据库查询
- 优化 SQL 查询
- 使用队列处理耗时任务

## 常用命令

```bash
# 启动开发服务器
php think run

# 清除缓存
php think clear

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

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

## 扩展安装

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