Browse Source

refactor: 改为多应用模式,控制器回到 app/api/controller/(符合代码规范)

规范《代码规范.md》第 27 行要求控制器位于 app/api/controller/Xxx.php。
上一轮为修复 404 曾挪到 app/controller/,属于违规且与规范冲突。

改动:
- app/controller/* -> app/api/controller/*,命名空间改为 app\api\controller
- 路由 app/api/route/api.php:规则去掉 api 前缀(多应用中间件会剥掉应用名),
  只写 v1/xxx,URL 仍是 /api/v1/xxx
- 根 route/ 清空:多应用下与应用内路由同时定义会让命中顺序不可预期
- 新增 app/index/ 默认应用:访问域名根路径返回服务状态与可用接口,便于排错
- composer.json 显式声明 topthink/think-multi-app(否则下次 composer install 会卸掉)

注意:部署后需 composer update topthink/think-multi-app 以刷新 composer.lock。
main
qian.guo 1 month ago
parent
commit
cdf796af99
14 changed files with 799 additions and 749 deletions
  1. +1
    -1
      app/api/controller/Auth.php
  2. +1
    -1
      app/api/controller/Common.php
  3. +1
    -1
      app/api/controller/Quiz.php
  4. +1
    -1
      app/api/controller/User.php
  5. +27
    -14
      app/api/route/api.php
  6. +0
    -18
      app/controller/Index.php
  7. +57
    -0
      app/index/controller/Index.php
  8. +2
    -1
      composer.json
  9. +12
    -15
      route/app.php

app/controller/Auth.php → app/api/controller/Auth.php View File

@ -10,7 +10,7 @@ declare(strict_types=1);
* E-mail: yiyezhiqiutel@gmail.com
*/
namespace app\controller;
namespace app\api\controller;
use app\BaseController;
use app\model\UserModel;

app/controller/Common.php → app/api/controller/Common.php View File

@ -10,7 +10,7 @@ declare(strict_types=1);
* E-mail: yiyezhiqiutel@gmail.com
*/
namespace app\controller;
namespace app\api\controller;
use app\BaseController;
use app\service\ScoreService;

app/controller/Quiz.php → app/api/controller/Quiz.php View File

@ -10,7 +10,7 @@ declare(strict_types=1);
* E-mail: yiyezhiqiutel@gmail.com
*/
namespace app\controller;
namespace app\api\controller;
use app\BaseController;
use app\model\QuizModel;

app/controller/User.php → app/api/controller/User.php View File

@ -10,7 +10,7 @@ declare(strict_types=1);
* E-mail: yiyezhiqiutel@gmail.com
*/
namespace app\controller;
namespace app\api\controller;
use app\BaseController;
use app\model\UserModel;

route/api.php → app/api/route/api.php View File

@ -2,25 +2,38 @@
declare(strict_types=1);
/**
* api.php
* Created by PhpStorm.
* Date: 2026/10/17
* Time: 09:40
* Author: qian.guo
* E-mail: yiyezhiqiutel@gmail.com
*/
* api.php
* Created by PhpStorm.
* Date: 2026/10/17
* Time: 09:40
* Author: qian.guo
* E-mail: yiyezhiqiutel@gmail.com
*
* 本文件:api 应用的路由
*
* 位置说明(多应用模式):
* 应用名 = api,所以本文件在 app/api/route/ 下。
* 多应用中间件会先取 URL 第一段作为应用名并把它从 pathinfo 中剥掉,
* 因此这里**不需要再写 api 前缀**,规则从 v1/ 开始。
*
* URL: /api/v1/health
* 应用: api ← 被剥掉
* 规则: v1/health ← 本文件的写法
* 控制器: app\api\controller\Common::health
*
* 为什么不用根 route/ 目录:
* 多应用模式下每个应用有独立的 route/ 目录。根 route/ 只在未进入应用时生效,
* 两边同时定义会让「哪条规则命中」变得不可预期,所以根 route/ 保持为空。
*
* 鉴权策略:需要登录的路由挂 LoginCheck,不需要的不挂。
* 不用「全局挂载 + 控制器内判断」—— 那种写法迟早会漏判一处。
*/
use app\middleware\LoginCheck;
use app\middleware\RateLimitCheck;
use think\facade\Route;
/*
| 全部 API 路由,统一前缀 /api/v1
|
| 鉴权策略:需要登录的路由挂 LoginCheck,不需要的不挂
| 不用「全局挂载 + 控制器内判断」—— 那种写法迟早会漏判一处
*/
Route::group('api/v1', function () {
Route::group('v1', function () {
Route::get('health', 'Common/health');

+ 0
- 18
app/controller/Index.php View File

@ -1,18 +0,0 @@
<?php
namespace app\controller;
use app\BaseController;
class Index extends BaseController
{
public function index()
{
return '<style>*{ padding: 0; margin: 0; }</style><iframe src="https://www.thinkphp.cn/welcome?version=' . \think\facade\App::version() . '" width="100%" height="100%" frameborder="0" scrolling="auto"></iframe>';
}
public function hello($name = 'ThinkPHP8')
{
return 'hello,' . $name;
}
}

+ 57
- 0
app/index/controller/Index.php View File

@ -0,0 +1,57 @@
<?php
declare(strict_types=1);
/**
* Index.php
* Created by PhpStorm.
* Date: 2026/10/18
* Time: 03:55
* Author: qian.guo
* E-mail: yiyezhiqiutel@gmail.com
*/
namespace app\index\controller;
use app\BaseController;
/**
* 默认应用首页
*
* 为什么需要这个应用:
* 多应用模式要求每个 URL 第一段是应用名。config/app.php 的 default_app 是 index,
* 所以访问域名根路径 `/` 会落到这里。没有它的话,打开域名只会得到 404,
* 而 404 又会被统一异常处理器渲染成 JSON —— 看上去像「接口不存在」,
* 很难判断是「服务活着但没首页」还是「整个服务挂了」。
*
* 为什么返回 JSON 而不是网页:
* 本项目是纯 API 后端,没有视图层(装的是骨架自带的 view/ 空目录)。
* 返回一段列出可用接口的 JSON,比返回 HTML 更能直接用于排错:
* 能打开它就证明「域名 → Nginx → PHP → 框架 → 路由 → 控制器」整条链路通了。
*/
class Index extends BaseController
{
/**
* 首页
* index
* @return \think\response\Json
*/
public function index()
{
$data = [];
$data['service'] = 'zhunxin-api';
$data['status'] = 'ok';
$data['message'] = '服务运行中,这是一个 API 服务,请访问接口';
// 列出可用入口,便于直接在浏览器里点开验证
$data['endpoints'] = [];
$data['endpoints']['health'] = '/api/v1/health';
$data['endpoints']['paper'] = '/api/v1/quiz/paper';
$data['endpoints']['submit'] = '/api/v1/quiz/submit(POST)';
return json([
'code' => config('code.success'),
'msg' => 'success',
'data' => $data
]);
}
}

+ 2
- 1
composer.json View File

@ -23,7 +23,8 @@
"php": ">=8.0.0",
"topthink/framework": "^8.0",
"topthink/think-orm": "^3.0|^4.0",
"topthink/think-filesystem": "^2.0|^3.0"
"topthink/think-filesystem": "^2.0|^3.0",
"topthink/think-multi-app": "^1.0"
},
"require-dev": {
"topthink/think-dumper": "^1.0",


+ 12
- 15
route/app.php View File

@ -4,26 +4,23 @@ declare(strict_types=1);
/**
* app.php
* Created by PhpStorm.
* Date: 2026/10/17
* Time: 16:40
* Date: 2026/10/18
* Time: 03:55
* Author: qian.guo
* E-mail: yiyezhiqiutel@gmail.com
*
* 路由加载入口
* 根路由文件(多应用模式下**刻意留空**)
*
* 官方骨架的 app.php 带两条示例路由(GET /think、GET /hello/:name),已删除:
* - 它们是脚手架演示用,不是本项目接口
* - 留在生产环境等于对外暴露两个无用端点,还会被扫描器记成"可访问路径"
* 为什么留空:
* 装 think-multi-app 后,路由按应用拆分,定义在
* app/{应用名}/route/*.php
* 本项目 API 的路由在 app/api/route/api.php。
*
* 真正的接口定义在同目录的 api.php。本文件只做一件事:确保它被加载。
* 根 route/ 只在「未进入任何应用」时才生效。如果这里也定义规则,
* 会出现两套规则争抢同一 URL 的情况,而命中顺序取决于加载次序,
* 排查时会非常痛苦(同一请求有时对有时错)。
*
* 为什么要显式 require:
* 多数 TP8 版本会扫描 route/ 下所有 php 文件,但也有只加载 route/app.php 的情况。
* 靠"应该会扫到"是赌运气,赌输的表现是全部接口 404,
* 而报错只说"控制器不存在",很难联想到是路由文件没被加载。
*
* 用 require_once 而不是 require:
* 若框架同时也扫到了 api.php,require_once 会走已加载判断,不会重复执行。
* 所以:根路由不写任何规则。需要全局拦截请用中间件,不要用路由。
*/
require_once __DIR__ . '/api.php';
// 有意为空。请勿在此添加 Route:: 规则,原因见上方说明。

Loading…
Cancel
Save