常见问题

• 如何使用Knife4j调试接口？
• 代码报错：xxxDef找不到怎么办？
• 启动报错：Error creating bean with name 'flywayInitializer' 怎么办？

如何使用Knife4j调试接口？

Sz-Admin 集成了 Knife4j，强大的接口调试工具，旨在简化后端开发人员的自测流程以及与前端的协同工作。

访问接口文档

首先，打开以下地址以访问我们的API文档：

# api 文档地址
http://127.0.0.1:9991/api/admin/doc.html#

导航至特定API组

• 点击界面左上角的下拉菜单，选择您需要调试的API组。

选择并调试接口

• 浏览并选择您想要调试的接口目录。

接口调试步骤

1. 接口权限验证：大多数接口需要通过权限验证，包括token和用户权限检查。

2. 配置全局Header：为了通过token验证，请按照以下步骤配置。

获取Token

• 打开浏览器的开发者工具（通常通过按F12或右键点击页面选择检查）。
• 选择Fetch/XHR标签，任意选择一个请求。
• 查看Headers中的Request Headers，特别关注Authorization项。

设置全局Token

• 复制Authorization属性值，并按照以下步骤在Knife4j中进行设置。

配置展示

• 配置完成后，界面将显示您设置的全局参数。

刷新页面

！！！重要提示：配置全局参数后，请务必手动刷新页面（按F5），以确保设置生效！！！

开始调试

• 一旦设置完成，我们就可以自由地调试任何接口了。

---

代码报错：xxxDef找不到怎么办？

MyBatis-Flex 使用了 APT 技术，xxxDef是自动生成的，需要编译项目。如果已经生成但还提示报错参照下述方法进行标记。

---

启动报错：Error creating bean with name 'flywayInitializer' 怎么办？

Sz-Admin 采用Flyway作为版本控制工具，以确保数据库升级的一致性和可追溯性。Flyway会在版本冲突时自动报错并尝试回滚至安全基线版本^[1]。以下是一些常见的问题及其解决方案：

问题一：DDL脚本与数据库结构冲突

示例：DDL中新增了一张teacher表，但是数据库中已经存在了teacher表。

解决方案：

1. 分析日志：Flyway会记录每条脚本的执行情况，找出冲突点（teacher表已存在）。

2. 解决冲突：如果是因为结构已存在，考虑删除或重命名冲突的表。

3. 清理版本记录：删除t_db_version表中对应的版本记录（version 1.7），确保版本一致性。

4. 重新启动服务：完成上述步骤后，重新启动服务以恢复正常。

   

问题二：DDL脚本版本冲突

示例：当前版本为v1.7，而后我们又修改了DDL文件（V1.7__20240624_Update_DDL.sql）。

解决方案：

1. 识别冲突：查看Flyway日志，确定冲突的版本号。

2. 清理版本记录：删除t_db_version表中的冲突版本记录

替代方案：禁用Flyway（不推荐）

如果上述方法不适用，可以考虑临时禁用Flyway，通过修改flyway.yml配置文件实现。

IMPORTANT

注意： 我们强烈推荐使用Flyway来严格控制数据库脚本，以降低维护成本和避免潜在的生产事故。

最佳实践建议：

• 保持本地和测试环境的分离。
• 在开发阶段，使用客户端直接操作数据库时，务必记录所有变更。
• 在验证阶段，根据记录编写并测试升级脚本。
• 遇到问题时，检查DDL脚本记录，快速定位并解决问题。

---

1. 基线版本通常是一个特定的版本，它是一个已知的、稳定的数据库状态，可以作为迁移的起点。 ↩︎