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

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

```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/index`
- **Method**: GET
- **响应示例**:
```json
{
    "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
- **响应示例**:
```json
{
    "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`: 密码（必填）
- **响应示例**:
```json
{
    "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`: 邮箱
- **响应示例**:
```json
{
    "code": 200,
    "msg": "注册成功",
    "data": {
        "user_id": 1001
    },
    "time": 1640000000
}
```

### 认证接口（需要 token）

#### 5. 获取用户信息
- **URL**: `/api/user/info`
- **Method**: GET
- **Headers**: `token: your_token`
- **响应示例**:
```json
{
    "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. 统一响应格式
```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',
]);

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

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

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

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

## 扩展安装

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