常见问题

• 如何使用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: 添加上游仓库

首先，您需要添加上游仓库作为远程仓库的参考。这可以通过以下命令完成：

git remote add upstream https://github.com/feiyuchuixue/sz-boot-parent.git

步骤 2: 从上游仓库获取最新代码

执行以下命令从上游仓库获取最新的代码和分支信息：

git fetch upstream

执行此命令后，您将看到如下输出，这表示已成功获取了上游仓库的所有分支和标签：

remote: Enumerating objects: 3471, done.
remote: Counting objects: 100% (1874/1874), done.
remote: Compressing objects: 100% (902/902), done.
remote: Total 3471 (delta 821), reused 1642 (delta 667), pack-reused 1597 (from 1)
Receiving objects: 100% (3471/3471), 777.10 KiB | 2.47 MiB/s, done.
Resolving deltas: 100% (1273/1273), done.
From https://github.com/feiyuchuixue/sz-boot-parent
 * [new branch]      bugfix-0915   -> upstream/bugfix-0915
 * [new branch]      debounce      -> upstream/debounce
 * [new branch]      dependabot/maven/sz-dependencies/dev/com.alibaba-easyexcel-4.0.3 -> upstream/dependabot/maven/sz-dependencies/dev/com.alibaba-easyexcel-4.0.3
 * [new branch]      dev           -> upstream/dev
 * [new branch]      download      -> upstream/download
 * [new branch]      main          -> upstream/main
 * [new branch]      message       -> upstream/message
 * [new branch]      template_file -> upstream/template_file
 * [new branch]      upgrade       -> upstream/upgrade
 * [new tag]         v0.7.6        -> v0.7.6
 * [new tag]         v0.7.9        -> v0.7.9
 * [new tag]         v0.6.0        -> v0.6.0
 * [new tag]         v0.6.1        -> v0.6.1
 * [new tag]         v0.6.2        -> v0.6.2
 * [new tag]         v0.6.3        -> v0.6.3
 * [new tag]         v0.6.4        -> v0.6.4
 * [new tag]         v0.6.5        -> v0.6.5
 * [new tag]         v0.7.1        -> v0.7.1
 * [new tag]         v0.7.2        -> v0.7.2
 * [new tag]         v0.7.3        -> v0.7.3
 * [new tag]         v0.7.4        -> v0.7.4
 * [new tag]         v0.7.5        -> v0.7.5
 * [new tag]         v0.7.7        -> v0.7.7
 * [new tag]         v0.7.8        -> v0.7.8

步骤 3: 选择分支进行合并

在合并上游分支之前，请确保您已经切换到目标分支。例如，如果您想合并main分支，您可以使用以下命令：

git checkout main

然后，您可以使用以下命令将上游的main分支合并到您的本地分支：

git merge upstream/main --allow-unrelated-histories

处理合并冲突

如果在合并过程中出现冲突，您需要手动解决这些冲突。解决冲突后，不要忘记提交您的更改：

git add .
git commit -m "Resolve merge conflicts"

以下是合并分支时可能遇到的界面：

如果在首次合并时遇到“refusing to merge unrelated histories”错误，可以使用上述命令解决。git merge upstream/main --allow-unrelated-histories

---

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