Initial commit: ThinkPHP refactor (tp)

Made-with: Cursor
2026-04-02 02:13:12 +00:00
commit 166940d5a6
127 changed files with 22225 additions and 0 deletions
@@ -0,0 +1,330 @@
+# 常见问题 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: URL 格式为 `http://域名/应用名/控制器/方法`
+- 示例：`http://localhost:8000/api/index/index`
+- 或使用路由：`http://localhost:8000/api/index`（需配置路由）
+
+### Q: 如何添加新的路由？
+A: 在 `route/api.php` 文件中添加路由规则：
+```php
+Route::get('user/profile', 'api.User/profile');
+Route::post('user/update', 'api.User/update');
+```
+
+### Q: 如何设置路由参数？
+A: 使用 `:参数名` 格式：
+```php
+Route::get('user/:id', 'api.User/detail');
+```
+
+## 3. 控制器开发
+
+### Q: 如何创建新的控制器？
+A:
+1. 手动创建：在 `app/api/controller/` 目录下创建 PHP 文件
+2. 使用命令：`php think make:controller api@Demo`
+
+### 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, 'app\api\validate\User.register');
+```
+
+### 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('api', function () {
+    Route::get('user/info', 'api.User/info');
+})->middleware(\app\api\middleware\Auth::class);
+```
+
+## 6. 数据库操作
+
+### Q: 如何使用模型？
+A:
+```php
+// 查询单条
+$user = \app\api\model\User::find(1);
+
+// 查询多条
+$users = \app\api\model\User::where('status', 1)->select();
+
+// 新增
+$user = new \app\api\model\User;
+$user->username = 'test';
+$user->save();
+
+// 或
+\app\api\model\User::create([
+    'username' => 'test',
+    'password' => '123456',
+]);
+
+// 更新
+\app\api\model\User::update(['id' => 1, 'status' => 0]);
+
+// 删除
+\app\api\model\User::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