nepiedg
e0733cf672
- Updated API routes to use a unified versioning scheme under `/api/v1/auth`. - Implemented new authentication controller for login, registration, and token management. - Removed legacy user and index controllers, along with associated models and validation files. - Updated documentation to reflect new API endpoints and usage. - Cleaned up unused service and middleware files to streamline the application structure.
338 lines
6.8 KiB
Markdown
338 lines
6.8 KiB
Markdown
# 常见问题 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 = password_hash('123456', PASSWORD_DEFAULT);
|
||
$member->save();
|
||
|
||
// 或
|
||
\app\api\model\Member::create([
|
||
'username' => 'test',
|
||
'password' => password_hash('123456', PASSWORD_DEFAULT),
|
||
]);
|
||
|
||
// 更新
|
||
\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
|