# autoApi **Repository Path**: liuqi_li/autoApi ## Basic Information - **Project Name**: autoApi - **Description**: API 一体化协作平台：接口设计/调试/Mock/文档/自动化测试/Swagger导入/RBAC - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-21 - **Last Updated**: 2026-09-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # autoApi > 轻量级 API 研发协作平台（Apifox 风格自研实现）：接口设计、调试、Mock、文档、自动化测试一体化。 autoApi 是一个面向中小团队/个人的 API 全生命周期管理工具，覆盖从 **接口设计 → 调试联调 → Mock 数据 → 文档导出 → 自动化回归** 的完整链路，并内置 **JWT 鉴权 + RBAC 权限体系** 与 **Swagger/OpenAPI 一键导入**，开箱即用（H2 零配置启动，可一键切换 MySQL）。 --- ## 一、技术栈 | 端 | 技术 | 版本 | |----|------|------| | 后端 | Spring Boot | 2.7.18（Java 8） | | 后端 | MyBatis-Plus | 3.5.3.1（注解式 Mapper，无 XML） | | 后端 | H2（默认）/ MySQL 8 | H2 2.1.214（文件库，MODE=MySQL）/ mysql-connector-j 8.0.33 | | 后端 | JWT 鉴权 | jjwt 0.11.5（HS256） | | 后端 | 密码加密 | spring-security-crypto BCrypt | | 后端 | PDF 导出 | OpenPDF 1.3.30 + itext-asian（中文 STSong-Light） | | 前端 | Vue 3 + Vite | Vue 3.4 / Vite 5.2 | | 前端 | UI 组件库 | Element Plus 2.7 | | 前端 | 状态管理 / 路由 | Pinia 2.1 / Vue Router 4.3 | | 前端 | HTTP | Axios 1.6 | **服务端口**：后端 `8080`（context-path `/api`）、前端 `5173`（dev，代理 `/api` → 8080） --- ## 二、功能模块总览 | 模块 | 核心功能点 | |------|-----------| | 认证与权限 | JWT 登录、路由守卫、页面级权限（meta.perm）、接口级权限（@RequirePermission） | | 项目管理 | 项目 CRUD、全局参数（全局 Headers / Query） | | 接口管理 | 分组、参数编辑器（嵌套 children）、请求体、响应结构、版本快照与回滚、批量删除、分页加载 | | 接口调试 | 真实 HTTP 转发（Query/Header/Path/Body）、调用日志记录与查询 | | Mock 服务 | Mock.js 风格规则、实时预览、按项目路由的 Mock 接口（含延时配置） | | 文档导出 | Markdown / HTML / PDF（中文）三种格式 | | 自动化测试 | 多步骤执行、并发组、全局变量、提取变量注入、自定义断言 | | 数据导入 | Swagger 2.0 / OpenAPI 3.x 解析、$ref 嵌套转换、按路径/名称/分组筛选 | | 系统管理 | 用户管理、角色管理、权限点管理（18 个权限点） | | 基础能力 | 主题系统（3 套主题色 + 亮/暗模式）、H2/MySQL 双库兼容、首次建库自动初始化 | --- ## 三、功能详解 ### 1. 认证与权限（RBAC） - **JWT 登录**：`POST /api/auth/login` 签发 HS256 Token，前端存储于 `localStorage`，请求头 `Authorization: Bearer `。 - **密码安全**：BCrypt 加密存储，不落明文。 - **页面级权限**：路由 `meta.perm` 控制（如 `user:view`），无权访问自动拦截并提示。 - **接口级权限**：后端 `@RequirePermission` 注解 + 自定义 `AuthInterceptor` 拦截校验。 - **默认角色**：`admin` 超级管理员 / `member` 普通成员 / `guest` 访客，共 **18 个权限点**（项目、接口、调试、Mock、文档、测试、用户、角色等查看/管理维度）。 - 系统内置 `RbacDataInitializer`：空库首次启动自动初始化权限点、角色及分配关系。 ### 2. 项目管理 - 项目 CRUD（列表分页、详情、新建、编辑、删除）。 - **全局参数**：每个项目可配置全局 Headers / Query，调试/测试/Mock 时自动合并到请求。 - 项目卡片展示在线状态、Base URL、接口数等概览。 ### 3. 接口管理（核心） - **接口列表**：左侧分组树 + 接口列表，**分页加载** + 大字段（responseSchema/bodyRaw/mockConfig）裁剪，保证大数据量下的响应时效。 - **分组**：接口按 `groupName` 分组展示，**支持折叠 / 删除分组（批量删除组内接口）**。 - **接口设计**（`ApiDesign`）： - 方法（GET/POST/PUT/DELETE/PATCH/...）、路径、名称、描述； - 参数编辑器 `KvEditor`：Query / Header / Path 三类参数，支持 `array/object` 类型**嵌套 children** 无限层级； - 请求体：`none` / `raw-json`（**自动 JSON 格式化**，2 空格缩进，含手动「格式化 JSON」按钮）/ `form-data`； - 响应结构：字段名、类型、描述、Mock 规则、示例值，嵌套 children； - 保存即生成**版本快照**（`ApiVersion`）。 - **版本管理**：历史版本列表、查看任意版本详情、**一键回滚**（`POST /apis/{id}/rollback/{version}`）。 - **批量操作**：列表复选框 + 批量删除（`POST /apis/batch-delete`，级联清理版本与调用日志）。 ### 4. 接口调试（Debug 代理） - `POST /api/debug/run`：后端作为**代理**真实转发请求到目标地址，支持 Query / Header / Path 参数、raw-json / form-data 请求体，自动带全局参数。 - **调用日志**：每次调试记录状态码、耗时、请求/响应体，可查看详情、按接口查询、清空历史。 - 全局超时配置（连接 10s / 读取 30s，可在 `application.yml` 调整）。 ### 5. Mock 服务 - `POST /api/mock/preview`：实时预览 Mock 结果。 - `GET /api/mock/{projectId}/**`：**按项目路由的真实 Mock 接口**，前端可直接请求。 - **Mock.js 风格规则**：`@cname @email @integer(1,100) @float(1,10,1,2) @boolean @url @image @datetime @city @address @ip @paragraph` 等，自动按字段类型生成示例。 - 支持自定义延时（`mock.default-delay`）。 ### 6. 文档导出 - `GET /api/doc/{projectId}/markdown`：Markdown 文档（GitHub 风格，可复制到任意平台）。 - `GET /api/doc/{projectId}/html`：HTML 文档页。 - `GET /api/doc/{projectId}/pdf`：**PDF 导出**（OpenPDF + STSong-Light 内置中文字体，无需安装字体），浏览器直接下载。 ### 7. 自动化测试 - `POST /api/test/run`：按**测试步骤**顺序执行（支持步骤标记 `parallel` 组成**并发组**）。 - **变量体系**： - 全局变量（`${name}` 占位符自动替换）； - **提取变量**：步骤响应字段（JSONPath）提取为变量，供后续步骤引用 → 实现接口间参数传递； - 并发组内共享「组开始时刻」变量快照，结束后合并回主上下文。 - **自定义断言**：类型支持 `status`（状态码）/ `body`（响应体字段，JSONPath）/ `header`（响应头）/ `bodyContains`（包含文本）；运算符支持 `eq / neq / contains / exists / regex / gt / lt`。 ### 8. Swagger / OpenAPI 导入 - 支持 **Swagger 2.0**（`definitions` / body / formData）与 **OpenAPI 3.x**（`components.schemas` / requestBody）。 - **$ref 递归解析**：自动展开嵌套引用，并合并 **allOf / oneOf / anyOf** 组合 schema（继承/组合模型不丢失字段）。 - **请求体映射**：JSON 对象属性自动映射到 Query 参数（嵌套对象 → children），**同时保留原始 bodyRaw**。 - **导入筛选**：预览列表支持按 **路径 / 名称 / 分组** 三个维度筛选（不区分大小写子串匹配），「全选」作用于筛选结果，被筛掉的接口不会被导入。 - **大文档保护**：schema 展开限制最大深度（6 层）与节点数（300 个），防止超大响应体导致前端崩溃；预览走轻量解析、导入时全量解析。 - 导入流程：粘贴 JSON / 上传文件 → 预览勾选（分页渲染）→ 一键导入（自动建版本）。 ### 9. 系统管理 - **用户管理**：用户 CRUD、分配角色、启用/停用。 - **角色管理**：角色 CRUD、勾选权限点（18 个）。 - **权限点**：`GET /api/permissions` 返回全量权限树，供角色分配使用。 ### 10. 基础能力 - **主题系统**：蓝色 / 橙色 / 绿色三套科技风主题 + 亮/暗模式，选择持久化到 `localStorage`。 - **数据库双兼容**：`schema.sql` 使用 `DATETIME DEFAULT CURRENT_TIMESTAMP` + 内联 `INDEX`，同时兼容 H2（MODE=MySQL）与真实 MySQL 8。 - **首次建库自动初始化**：`DatabaseInitConfig` 启动时探测核心表 `project`，**仅在不存在时执行一次** `schema.sql` + `data.sql`，后续重启自动跳过（避免每次重跑建表脚本）。 --- ## 四、项目结构 ### 后端（Spring Boot） ``` backend/src/main/java/com/llq/autoapi/ ├── AutoApiApplication.java # 启动类（@MapperScan("com.llq.autoapi.mapper")） ├── controller/ # 11 个控制器（API 入口） │ ├── AuthController # 登录/登出/当前用户 │ ├── ProjectController # 项目 CRUD │ ├── ApiController # 接口 CRUD/分页/分组/版本/批量删除 │ ├── DebugController # 调试代理 + 调用日志 │ ├── MockController # Mock 预览 + 项目 Mock 服务 │ ├── DocController # Markdown/HTML/PDF 文档 │ ├── TestController # 自动化测试执行 │ ├── ImportController # Swagger 预览/导入 │ ├── UserController # 用户管理 │ ├── RoleController # 角色管理 │ └── PermissionController # 权限点 ├── service/ # 业务服务（DebugService/MockService/DocService/TestService/SwaggerImportService/PdfExportService/ApiVersionHelper） ├── entity/ # 7 张表实体（Project/ApiDefinition/ApiVersion/ApiCallLog/SysUser/SysRole/SysPermission） ├── mapper/ # MyBatis-Plus Mapper（注解式） ├── config/ # 配置（Cors/Security/Interceptor/MyBatisPlus/MetaObjectHandler/DatabaseInit） ├── common/ # Result 统一返回 / AuthContext / LoginUser ├── dto/ # 请求/响应 DTO（DebugRequest/Assertion/Extract/GlobalVar/TestRunRequest/...） ├── util/ # JwtUtil / MockUtil / JsonUtil ├── interceptor/ # AuthInterceptor（JWT + @RequirePermission） ├── annotation/ # RequirePermission └── init/ # RbacDataInitializer（默认权限/角色初始化） ``` ### 前端（Vue 3） ``` frontend/src/ ├── views/ # 页面 │ ├── Login.vue # 登录页（品牌展示 + 表单） │ ├── ProjectList.vue # 项目列表（卡片式） │ ├── ProjectDetail.vue # 项目详情（左侧分组树 + 5 个 Tab） │ ├── UserManagement.vue # 用户管理 │ └── RoleManagement.vue # 角色管理 ├── components/ # 组件 │ ├── Layout.vue # 主布局（顶栏导航） │ ├── ApiDesign.vue # 接口设计 Tab │ ├── ApiDebug.vue # 调试 Tab │ ├── ApiMock.vue # Mock Tab │ ├── ApiDoc.vue # 文档 Tab（Markdown/PDF 导出） │ ├── ApiTest.vue # 自动化测试 Tab │ ├── KvEditor.vue # 可编辑键值对组件（支持嵌套 children） │ ├── GlobalParamsDialog.vue # 全局参数弹窗 │ ├── SwaggerImportDialog.vue # Swagger 导入弹窗（筛选 + 勾选导入） │ ├── VersionHistoryDialog.vue # 版本历史/回滚弹窗 │ └── CallLogDialog.vue # 调用日志弹窗 ├── api/ # Axios 封装（index.js 全部接口 / request.js 拦截器） ├── store/ # Pinia（user 状态） ├── router/ # 路由 + 守卫（登录/权限） └── theme.js # 主题管理（三色 + 亮暗） ``` --- ## 五、快速开始 ### 环境要求 - JDK 8+、Maven 3.6+（后端） - Node.js 18+（前端） ### 1. 启动后端（默认 H2，零配置） ```bash cd backend mvn spring-boot:run # 启动于 http://localhost:8080/api ``` ### 2. 启动前端 ```bash cd frontend npm install npm run dev # 启动于 http://localhost:5173 ``` ### 3. 访问打开 `http://localhost:5173`，使用默认账号登录： | 账号 | 密码 | 角色 | |------|------|------| | `admin` | `admin123` | 超级管理员（全部权限） | > H2 控制台：`http://localhost:8080/api/h2-console`（JDBC URL：`jdbc:h2:file:./data/autoapi`，用户 `sa`，密码空） ### 4. 首次启动说明 - 空库首次启动自动执行 `schema.sql`（建表）+ `data.sql`（演示项目：示例：用户中心 API），后续重启自动跳过。 - 演示数据：1 个示例项目 + 若干示例接口，可直接体验设计/调试/Mock/文档/测试全流程。 --- ## 六、数据库切换（H2 → MySQL 8） 1. 创建数据库：`CREATE DATABASE autoapi DEFAULT CHARACTER SET utf8mb4;` 2. 编辑 `backend/src/main/resources/application.yml`：注释 H2 数据源块，取消注释末尾 MySQL 块（按需修改用户名/密码）。 3. 重启后端，首次启动自动建表并灌入演示数据。 > `schema.sql` / `data.sql` 均为 H2/MySQL 双兼容写法，`mysql-connector-j:8.0.33` 已在 `pom.xml` 中。 --- ## 七、主要 API 一览 | 模块 | 方法与路径 | 说明 | |------|-----------|------| | 认证 | `POST /api/auth/login` | 登录，签发 JWT | | 认证 | `GET /api/auth/me` | 当前用户信息与权限 | | 项目 | `GET/POST /api/projects`、`PUT/DELETE /api/projects/{id}` | 项目 CRUD（列表分页） | | 接口 | `GET /api/apis?projectId=&page=&size=` | 接口列表（轻量字段 + 分页） | | 接口 | `POST /api/apis`、`PUT/DELETE /api/apis/{id}` | 接口 CRUD | | 接口 | `POST /api/apis/batch-delete` | 批量删除（级联版本/日志） | | 接口 | `GET /api/apis/groups?projectId=` | 分组列表 | | 版本 | `GET /api/apis/{id}/versions`、`POST /api/apis/{id}/rollback/{version}` | 版本历史 / 回滚 | | 调试 | `POST /api/debug/run` | 调试代理（真实转发） | | 日志 | `GET /api/debug/apis/{apiId}/logs`、`DELETE` | 调用日志查询 / 清空 | | Mock | `POST /api/mock/preview`、`GET /api/mock/{projectId}/**` | Mock 预览 / 真实 Mock 接口 | | 文档 | `GET /api/doc/{projectId}/markdown\|html\|pdf` | 三种格式文档导出 | | 测试 | `POST /api/test/run` | 自动化测试执行 | | 导入 | `POST /api/import/swagger/preview`、`POST /api/import/swagger` | Swagger 预览 / 导入 | | 用户 | `GET/POST /api/users`、`PUT/DELETE /api/users/{id}` | 用户管理 | | 角色 | `GET/POST /api/roles`、`PUT/DELETE /api/roles/{id}` | 角色管理 | | 权限 | `GET /api/permissions` | 权限点列表 | --- ## 八、关键设计说明 - **统一返回体**：所有接口返回 `Result{code, message, data}`，前端 axios 拦截器统一处理错误与登录失效。 - **逻辑删除**：MyBatis-Plus `logic-delete-field: deleted`，删除为软删除，列表默认过滤。 - **大字段裁剪**：接口列表接口（`GET /apis`）默认不返回 `responseSchema/bodyRaw/mockConfig` 等大字段，详情接口按需全量返回。 - **版本快照**：每次保存接口自动生成 `ApiVersion` 快照（存全量 JSON），支撑历史回溯与回滚。 - **SQL 初始化幂等**：建表语句全部 `IF NOT EXISTS` + 内联索引，配合「仅首次执行」初始化器，任意次重启无副作用。 - **Mock 兼容 Mock.js 语法**：`MockUtil` 内置解析器，支持常用占位符，无需引入外部库。 --- ## 九、后续规划（可选） - 环境管理（多环境 Base URL 切换） - 接口级 Mock 规则持久化与开关 - 自动化测试报告导出（HTML/PDF） - 团队协作与操作审计日志 --- ## License 本项目采用 [Apache License 2.0](LICENSE) 开源协议。 ``` Copyright (c) 2026 liuqi_li ``` --- *autoApi · API 一体化协作平台 · 2026*