mini_tp/FAQ.md

# 常见问题 FAQ

## 1. 安装和配置

### Q: 如何修改默认应用？
A: 编辑 `config/app.php` 文件，修改 `default_app` 配置：
```php
'default_app' => 'api',
```

### Q: 如何配置数据库？
A: 编辑 `.env` 文件，修改数据库连接信息：
```env
[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = tp_api
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8mb4
```

### Q: 如何开启调试模式？
A: 在 `.env` 文件中设置：
```env
APP_DEBUG = true
```

## 2. 路由和访问

### Q: 如何访问 API 接口？
A: 当前项目使用固定路由入口，认证接口统一走 `http://域名/api/v1/auth/*`
- 登录：`POST http://localhost:8000/api/v1/auth/login`
- 注册：`POST http://localhost:8000/api/v1/auth/register`
- 当前用户：`GET http://localhost:8000/api/v1/auth/me`

### Q: 如何添加新的路由？
A: 在 `app/api/route/app.php` 文件中添加路由规则：
```php
use app\api\controller\v1\Auth;

Route::post('v1/auth/login', [Auth::class, 'login']);
Route::post('v1/auth/register', [Auth::class, 'register']);
```

### Q: 如何设置路由参数？
A: 使用 `:参数名` 格式：
```php
Route::get('v1/example/:id', 'v1.Example/detail');
```

## 3. 控制器开发

### Q: 如何创建新的控制器？
A:
1. 手动创建：在 `app/api/controller/v1/` 目录下创建 PHP 文件
2. 使用命令：`php think make:controller api@v1/Auth`

### Q: 如何返回 JSON 数据？
A: 使用基础控制器提供的方法：
```php
// 成功响应
return $this->success($data, '操作成功');

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

// 或使用 json() 函数
return json(['code' => 200, 'data' => $data]);
```

### Q: 如何获取请求参数？
A:
```php
// GET 参数
$data = $this->request->get();

// POST 参数
$data = $this->request->post();

// 所有参数
$data = $this->request->param();

// 单个参数
$name = $this->request->param('name');
```

## 4. 数据验证

### Q: 如何验证请求数据？
A:
1. 在控制器中直接验证：
```php
$this->validate($data, [
    'username' => 'require|length:3,20',
    'email' => 'require|email',
]);
```

2. 使用验证器：
```php
$this->validate($data, [
    'username' => 'require|alphaNum',
    'password' => 'require|length:6,20',
]);
```

### Q: 如何自定义验证错误信息？
A:
```php
$this->validate($data, $rules, [
    'username.require' => '用户名不能为空',
    'email.email' => '邮箱格式不正确',
]);
```

## 5. 中间件

### Q: 如何创建中间件？
A:
```php
<?php
namespace app\api\middleware;

class CheckToken
{
    public function handle($request, \Closure $next)
    {
        // 前置中间件
        $token = $request->header('token');
        if (empty($token)) {
            return json(['code' => 401, 'msg' => '未授权']);
        }

        return $next($request);
    }
}
```

### Q: 如何使用中间件？
A:
1. 全局中间件：在 `app/api/middleware.php` 中注册
2. 路由中间件：在路由定义中使用
```php
Route::group('v1/auth', function () {
    Route::get('me', [\app\api\controller\v1\Auth::class, 'me']);
})->middleware(\app\api\middleware\Auth::class);
```

## 6. 数据库操作

### Q: 如何使用模型？
A:
```php
// 查询单条
$member = \app\api\model\Member::findByUserid(1);

// 查询多条
$members = \app\api\model\Member::where('disabled', 0)->select();

// 新增
$member = new \app\api\model\Member;
$member->username = 'test';
$member->password = \app\api\model\Member::makePassword('123456');
$member->save();

// 或
\app\api\model\Member::create([
    'username' => 'test',
    'password' => \app\api\model\Member::makePassword('123456'),
]);

// 更新
\app\api\model\Member::update(['userid' => 1, 'disabled' => 1]);

// 删除
\app\api\model\Member::destroy(1);
```

### Q: 如何使用事务？
A:
```php
use think\facade\Db;

Db::startTrans();
try {
    // 数据库操作
    Db::commit();
} catch (\Exception $e) {
    Db::rollback();
}
```

## 7. 缓存

### Q: 如何使用缓存？
A:
```php
use think\facade\Cache;

// 设置缓存
Cache::set('key', 'value', 3600);

// 获取缓存
$value = Cache::get('key');

// 删除缓存
Cache::delete('key');
```

## 8. 跨域问题

### Q: 如何解决跨域问题？
A:
1. 项目已内置跨域中间件 `CrossDomain`
2. 确保中间件已注册到 `app/api/middleware.php`
3. 前端请求时需要设置正确的 headers

## 9. 认证授权

### Q: 如何实现 Token 认证？
A:
1. 安装 JWT 扩展：`composer require firebase/php-jwt`
2. 在登录接口生成 Token
3. 在中间件中验证 Token
4. 参考 `app/api/middleware/Auth.php`

### Q: 如何实现接口签名验证？
A:
1. 前端按照规则生成签名
2. 后端在中间件中验证签名
3. 签名规则：`md5(参数排序后的字符串 + 密钥 + 时间戳)`

## 10. 性能优化

### Q: 如何优化接口性能？
A:
1. 开启路由缓存：`php think route:list`
2. 使用缓存减少数据库查询
3. 优化 SQL 查询，避免 N+1 问题
4. 使用队列处理耗时任务
5. 开启 OPcache

### Q: 如何开启路由缓存？
A:
```bash
php think route:list
```

## 11. 错误处理

### Q: 如何自定义错误响应？
A:
1. 修改 `app/ExceptionHandle.php`
2. 自定义异常处理逻辑
3. 返回 JSON 格式的错误信息

### Q: 如何记录错误日志？
A:
```php
use think\facade\Log;

Log::error('错误信息', ['data' => $data]);
Log::info('提示信息');
Log::warning('警告信息');
```

## 12. 部署

### Q: 生产环境如何部署？
A:
1. 关闭调试模式：`APP_DEBUG = false`
2. 配置正确的数据库信息
3. 设置正确的目录权限
4. 配置 Nginx/Apache
5. 开启 OPcache
6. 使用缓存

### Q: 如何设置目录权限？
A:
```bash
chmod -R 755 /path/to/tp
chmod -R 777 /path/to/tp/runtime
```

## 13. 常见错误

### Q: 提示"控制器不存在"？
A:
1. 检查命名空间是否正确
2. 检查类名和文件名是否一致
3. 检查控制器是否继承正确的基类

### Q: 提示"方法不存在"？
A:
1. 检查方法名拼写
2. 检查方法访问修饰符（必须是 public）
3. 清除缓存：`php think clear`

### Q: 数据库连接失败？
A:
1. 检查 `.env` 配置是否正确
2. 检查数据库服务是否启动
3. 检查防火墙设置
4. 检查用户权限

## 14. 扩展功能

### Q: 如何添加更多应用？
A:
```bash
# 创建 admin 应用
mkdir -p app/admin/controller
# 然后创建控制器和配置文件
```

### Q: 如何使用队列？
A:
```bash
composer require topthink/think-queue
php think queue:listen
```

### Q: 如何使用定时任务？
A:
```bash
composer require topthink/think-cron
# 然后配置定时任务
```

## 更多帮助

如有其他问题，请查阅：
- ThinkPHP 官方文档：https://www.kancloud.cn/manual/thinkphp8
- 项目文档：README_API.md
- 提交 Issue：https://github.com/top-think/framework/issues