# ThinkPHP8 后端脚手架 **Repository Path**: darkwinoom/tp8-server-scaffold ## Basic Information - **Project Name**: ThinkPHP8 后端脚手架 - **Description**: 这是一个使用 ThinkPHP8.1 + MySQL + Swagger 搭建的示例，包含完整登录与鉴权功能，针对后端服务开发快速响应。可与个人项目中的前端脚手架配套使用 - **Primary Language**: PHP - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2024-09-22 - **Last Updated**: 2025-07-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: PHP, Composer, ThinkPHP, Swagger, Rest-api ## README # ThinkPHP8 后端脚手架 这是一个使用 ThinkPHP8.1 + MySQL + Swagger 搭建的示例，包含完整登录与鉴权功能，针对后端服务开发快速响应。 ![swagger](./docs//swagger.png) ![swagger-api](./docs//swagger-api.png) ## 环境要求 - PHP > 8.0 (推荐使用 8.1、8.2、8.3)； - PHP ext-sodium 扩展（lcobucci/jwt）； - MySql >= 5.6（推荐使用 8、9）； - php-cli 环境（支持Composer）； ## 特色功能 ### 基于 MVC 架构的 RESTful - 基于 MVC 架构的简化应用，支持 web 端与 api，快速开发响应； - api 基于 RESTful，内置 jwt 全局请求验证，完善的 accessToken 和 refreshToken 机制，注解式 swagger-ui 方便进行前后端开发并行； - 内置完整的 API 请求套件，包含登录、鉴权、系统用户、角色、菜单、部门管理、日志记录等，结构清晰简单方便理解； ### 内置 SSE 聊天补全 completions > 该功能目前处于试验探索阶段 关于聊天补全，openai 的定义如下： > Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. 使用该功能需要部署本地 LLM API，如：LM Studio、Ollama 等。结果如下图所示： ![SSE](./docs//swagger-sse.png) - Ollama本地部署官方指引： - LM Studio本地部署官方指引： 注：更多配置详情请访问文件 `app/controller/app/Llm.php` 查看。 ### 可搭配前端项目使用 本项目包含 `app` 和 `admin` 两组 API，可搭配本人其它前端项目作为其后端运行使用： - `admin` 对应项目 [vue3-admin-scaffold](https://gitee.com/darkwinoom/vue3-admin-scaffold)，支持项目 90% 的 API； - `app` 对应项目 [uni-app-scaffold](https://gitee.com/darkwinoom/vue3-app-scaffold) 和 [vue3-ai-scaffold](https://gitee.com/darkwinoom/vue3-ai-scaffold)，目前仅包括支持项目中用户登录与鉴权部分 API； ## 安装使用 本项目使用 `lcobucci/jwt`，需要安装 php 扩展 ext-sodium（windows 系统需要修改 php.ini 配置并开启 extension=sodium 即可）。 运行之前请安装 composer： ```bash composer install ``` ### 项目初始化 您可以使用以下命令进行项目初始化： ```bash # 默认初始化 php think init # 您也可以使用以下命令快速初始化 php think init --d ``` 运行后将会引导您配置并创建 `.env` 文件，文件创建后您可以随时修改其中内容或重新运行初始化。 ### 运行 ```bash php think run -p 8100 ``` 运行成功后，打开 SwaggerUI 地址： *其它支持的命令可通过查看 `package.json` 文件确认* ## 目录说明 ```md ├─app 应用目录 │ ├─command 指令工具 │ ├─controller 控制器 │ │ ├─admin admin API控制器 │ │ ├─app app API控制器 │ │ ├─web web 控制器 │ ├─middleware 中间件 │ ├─model 模型 │ ├─service 服务 │ ├─validate 验证器 │ ├─BaseController.php 控制器基础类 │ ├─common.php 应用公共文件 │ ├─event.php 事件定义文件 │ ├─ExceptionHandle.php 应用异常处理类 │ ├─middleware.php 全局中间件定义文件 │ ├─provider.php 容器Provider定义文件 │ ├─Request.php 应用请求对象类 ├─config 配置目录 │ ├─app.php 应用配置 │ ├─cache.php 缓存配置 │ ├─console.php 控制台配置 │ ├─cookie.php Cookie配置 │ ├─cors.php 跨域配置 │ ├─database.php 数据库配置 │ ├─filesystem.php 文件磁盘配置 │ ├─lang.php 多语言配置 │ ├─log.php 日志配置 │ ├─middleware.php 中间件配置 │ ├─route.php URL和路由配置 │ ├─session.php Session配置 │ ├─trace.php Trace配置 │ └─view.php 视图配置 ├─database 数据库目录 │ ├─migrations 数据库迁移 ├─public WEB目录（对外访问目录） │ ├─index.php 入口文件 │ ├─router.php 快速测试文件 │ └─.htaccess 用于apache的重写 │ ├─extend 扩展类库目录 ├─runtime 应用的运行时目录（可写，可定制） ├─vendor Composer类库目录 ├─view 视图目录 ├─.env 环境变量配置文件 ├─.travis.yml Travis CI配置文件 ├─composer.json composer定义文件 ├─LICENSE.txt tp8授权说明文件 ├─README.md README 文件 ├─think 命令行入口文件 ``` ## 配置说明 使用命令 `php think init` 后会在根目录生成配置文件 `.env`。 您可以在此修改部分服务器配置信息，参数说明如下： | 配置参数 | 描述说明 | | ------------------------- | ----------------------------------------------------- | | app_debug | 应用调试模式 | | app.name | 项目名称（英文） | | app.swagger_on | Swagger UI 开关 | | database.type | 数据库类型 | | database.host | 数据库服务地址 | | database.name | 数据库名 | | database.user | 数据库用户名 | | database.password | 数据库密码 | | database.port | 数据库端口 | | database.charset | 数据库编码 | | database.prefix | 数据库表前缀 | | jwt.issued_by | JWT 签发者 iss，需唯一且可验证 | | jwt.permitted_for | JWT 接收者 aud，需与接收方匹配 | | jwt.key_secrect | JWT 密钥签名信息，推荐 32 位字符串（请勿公开） | | jwt.expires_minute | JWT TOKEN 默认有效时间（单位：分钟） | | jwt.refresh_day | JWT Refresh TOKEN 默认有效期，每次刷新后重置（单位：天） | | sms.deadline_minute | 短信认证码有效时间（单位：分钟） | | sms.interval_second | 短信认证码发送间隔（单位：秒） | | default_lang | 默认语言包 | 其中 `jwt.issued_by`、`jwt.permitted_for`、`jwt.key_secrect` 在修改后会导致所有之前颁发的 token 立即失效，请特别注意。 ## Swagger 说明 本项目使用的 Swagger 为注解式的，仅需要作简单配置并在控制器（controller）中编写注解即可使用，所见即所得。 目前内置了 `app` 和 `admin`（可在 Swagger 页面右上角查看切换）api，您可以通过查看或修改内部文件注解进行使用。若您想要创建一个新的版本，可按以下步骤进行： - 在控制器目录 `app/controller` 中创建您想要开启的版本目录，然后将已有目录中的 `Swagger.php` 复制进去并修改标题、描述等信息； - 找到文件 `public/swagger/swagger-initializer.js`，添加对应路由页面到 `urls` 中，规则：`/swagger/api/[目录名称]/swagger.json`； - 创建任意子目录文件，使用注解标记即可（可通过查看已有目录中的标注方法）； ### 新增一组api 按照以下指引您可以创建一组新的 api： - 前往 `/public/swagger/swagger-initializer.js` 添加一个新的 url； - 在控制器 `/app/controller` 中添加对应新名称的文件夹，同时需要添加 `swagger.php` 作为相关说明； - 在 controller 完成 api，并在路由 `/route` 中创建对应路由规则即可 ### 关闭swagger 使用 Swagger 功能会让您的接口存在暴露风险，建议您仅在开发与测试时使用，对于生产环境中的项目，您可以参考以下步骤将其关闭： - 修改 `.env` 文件中 `app.swagger_on` 为 `false`，修改后您的 Swagger 页面将会被替换成空内容； - 移除 `public/swagger` 文件夹中所有内容（您也可以将其加密或移动到一个无法直接访问的位置），以阻止其被直接访问； ## 核心组件 - [ThinkPHP v8.1](https://www.thinkphp.cn/) - [zircote/swagger-php](https://github.com/zircote/swagger-php) - [lcobucci/jwt](https://github.com/lcobucci/jwt) - [swagger-ui v5.20.2](https://github.com/swagger-api/swagger-ui) ## 已知问题 - 使用聊天补全功能流输出（即 `stream = true`）时需要关闭 TP8 的 debug 模式，否则会因为附加的 trace 信息导致客户端无法失败响应内容； ## 开发方向 - [x] 命令行初始化项目，包括创建数据库 - [ ] 【进行中】接入其它个人前端项目： - [x] 接入 vue3-admin-scaffold - [ ] 【进行中】接入 vue3-ai-scaffold - [ ] 【进行中】接入 uni-app-scaffold - [ ] web 完整功能（bootstrap + webpack） - [ ] 消息队列功能 - [ ] 探索SSE聊天补全功能实现方案，包括深度思考、联网搜索等 - [ ] 完善单元测试、SSR、SSO等更多功能细节 待加入... ## Git 提交规范 - feat 增加新的业务功能 - fix 修复业务问题/BUG - perf 优化性能 - style 更改代码风格, 不影响运行结果 - refactor 重构代码 - revert 撤销更改 - test 测试相关, 不涉及业务代码的更改 - docs 文档和注释相关 - chore 更新依赖/修改脚手架配置等琐事 - workflow 工作流改进 - ci 持续集成相关 - types 类型定义文件更改 - wip 开发中 ## 开发环境 - php 8.1.28 - mysql 8.3.0 - composer 2.8.5 ## 附：参考文档 - [ThinkPHP8说明文档](https://doc.thinkphp.cn/v8_0/preface.html) - [Swagger php 注解常用语法梳理](https://www.sdk.cn/details/9pPQD6wqK09L8ozvNy)