常见问题

如何查看 OpenAPI 接口文档？

v2.0.0 基于 Spring Boot 4.x，~~Knife4j~~ 暂未作为当前主线适配，实际业务已暂停使用 Knife4j UI。当前接口文档由 Springdoc OpenAPI 提供，推荐访问 Swagger UI 或 OpenAPI JSON。

访问地址

shell

# Swagger UI
http://127.0.0.1:9991/api/swagger-ui.html

# OpenAPI JSON
http://127.0.0.1:9991/api/v3/api-docs

配置来源

当前仓库中配置文件名仍为 config/{profile}/knife4j.yml，这是历史命名。该文件内容实际是 springdoc 配置，例如 springdoc.swagger-ui.path=/swagger-ui.html、springdoc.api-docs.path=/v3/api-docs。

接口调试

先通过前端登录获取 Authorization 请求头，格式为 Bearer <token>。
在 Swagger UI 中找到鉴权或 Authorize 入口，填入完整 Authorization 值。
如果接口返回未登录或无权限，先确认 Sa-Token 白名单、当前用户角色权限，以及访问路径是否包含当前后端业务前缀，例如 /api/admin/**。

IMPORTANT

历史 http://127.0.0.1:9991/api/admin/doc.html# 是 Knife4j UI 入口，不再作为 v2.0.0 官网推荐入口。后续如果 Knife4j 完成 Spring Boot 4.x 适配，可再恢复对应说明。

代码报错：xxxDef（包*.table.xxxDef）找不到怎么办？

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

err-xxdef

启动报错：Liquibase changeSet 执行失败怎么办？

当前版本使用 Liquibase 管理数据库结构和初始化数据。常见报错通常来自表已存在、字段冲突、changeSet 被修改或历史版本表不一致。

问题一：表或字段已存在

如果你在已有数据库上启动 v2.0.0，可能出现官方初始化脚本与旧库结构冲突。请先确认：

当前库是否已经执行过旧版本脚本。
DATABASECHANGELOG 表中是否已有对应 changeSet。
冲突对象是否是自定义表或历史官方表。

存量库升级建议先在影子库演练。v2.0.0 涉及 ID、菜单、角色、字典和生成器表结构调整，不建议未经验证直接在生产库原地执行。

问题二：checksum 校验失败

已执行过的 changeSet 内容被修改后，Liquibase 会拒绝启动。处理方式：

确认 changeSet 修改是否来自官方升级或本地误改。
如果只是本地开发环境，可清空测试库后重新初始化。
如果是生产环境，先备份数据库，再评估是否需要执行 UPDATE DATABASECHANGELOG SET MD5SUM = NULL WHERE ID = 'xxx' 让 Liquibase 重新计算。

问题三：临时关闭 Liquibase

不推荐在长期环境关闭 Liquibase。确需临时排查时，可在当前数据库配置文件中设置：

yaml

spring:
  liquibase:
    enabled: false

IMPORTANT

关闭 Liquibase 只能用于排查，不能替代数据库迁移。生产环境应保持数据库结构与代码版本可追溯。

启动报错：java.nio.charset.MalformedInputException：Input length = 1怎么办？

java

启动报错：
Exception in thread "main" org.yaml.snakeyaml.error.YAMLException: java.nio.charset.MalformedInputException: Input length = 1

error-MIE

解决：

修改文件编码

err-MIE-encode

设置编码后需要maven清理并重新编译才会生效

maven clean && 重新编译

err-MIE-mvn

如何与官方（上游仓库）代码保持同步？

步骤 1: 添加上游仓库

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

shell

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

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

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

shell

git fetch upstream

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

shell

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分支，您可以使用以下命令：

shell

git checkout main

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

shell

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

处理合并冲突

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

shell

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

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

sz-admin Git 合并上游分支操作界面截图

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

sz-admin Git 解决 refusing to merge unrelated histories 错误截图

登陆报错： Cannot read properties of null (reading 'split')

在使用sz-admin进行登录操作时，您可能会遇到一个错误提示：“Cannot read properties of null (reading 'split')”。这通常表明应用程序在尝试访问一个未初始化或未定义的对象属性。

解决方案： 为了确保环境的一致性，sz-admin采用了基于环境的个性化配置。在本地开发环境中，默认使用的是.env.development.local配置文件，并且这个文件被设置为默认不被Git跟踪。

操作步骤：

创建配置文件：在项目根目录下，手动创建一个名为.env.development.local的文件。
设置初始参数：在.env.development.local文件中，根据项目需求配置必要的环境变量和初始参数。
重新启动应用：配置文件创建并设置完成后，重新启动您的应用程序。

重要提示： 请确保在本地开发环境中正确配置.env.development.local文件，以避免因环境变量未设置而导致的启动错误。

详见：快速开始--创建local环境。

项目中的数据库脚本在哪？怎么找不到？

Sz-Admin 当前使用 Liquibase 实现数据库结构和初始化数据同步。

v2.0.0 后脚本按模块拆分：

服务总入口：sz-service/sz-service-admin/src/main/resources/db/changelog/changelog-master.xml
Admin 模块入口：sz-module/sz-module-admin/src/main/resources/db/changelog/module-admin-changelog.xml
Generator 模块入口：sz-module/sz-module-generator/src/main/resources/db/changelog/module-generator-changelog.xml
framework：框架核心表和必要初始化数据。
generator：代码生成器表和初始化数据。
demo：演示数据，可按环境决定是否启用。

sz-admin Liquibase DDL 脚本目录结构截图

菜单设置了缓存 keep-alive 为什么不生效？

当给菜单设置了缓存 keep-alive 时，却发现未生效，这种情况很可能是由于菜单中的路由名称没有与页面组件名称（即通过 defineOptions 中的 name 属性所定义的名称）保持一致所导致的。只有确保二者名称完全对应，缓存功能才能正常发挥作用。

sz-admin keep-alive 路由名称与 defineOptions name 不一致导致缓存失效问题截图

数据权限配置了为什么不生效？

数据权限的核心机制依赖 @SaCheckPermission 注解触发，请逐项排查：

Controller 方法未添加 @SaCheckPermission 注解

数据权限拦截器只在检测到该注解时才会介入。如果接口方法使用了 @SaIgnore 或未添加任何鉴权注解，数据权限将不会生效。

java

// ✅ 正确：有 @SaCheckPermission，数据权限生效
@SaCheckPermission(value = "teacher.statistics.list", orRole = GlobalConstant.SUPER_ROLE)
@GetMapping
public ApiResult list(TeacherStatisticsListDTO dto) { ... }

sz.data-scope.enabled 配置为 false
检查 application.yml 中是否显式关闭了数据权限：
yaml
```
sz:
  data-scope:
    enabled: true  # 确保为 true
```
1
2
3
当前用户角色的数据权限范围未正确配置
登录后台，检查该用户所属角色在【角色管理 → 数据权限】中是否已正确设置权限范围（全部、部门及以下、仅本部门、仅本人、自定义）。
SQL 中缺少数据权限占位符
若使用自定义 XML SQL，需要确保 SQL 中包含数据权限注入的关联条件，否则框架无法自动拼接。详见数据权限文档。

多节点部署时出现主键冲突怎么办？

框架默认使用雪花ID生成主键，雪花算法通过 workerId + datacenterId 区分不同节点。若多个节点使用相同的 workerId 和 datacenterId，在同一毫秒内可能产生重复 ID，导致主键冲突。

相关说明可先查看配置 - mybatis-flex.yml 和规范 - 主键ID 与全局雪花ID策略。如果是从旧版本升级，还需要结合升级指南 - 全局 ID 迁移区分“运行期新 ID 生成”和“存量旧 ID 迁移”。

解决方案： 为每个节点配置唯一的环境变量：

shell

# 节点1
SZ_WORKER_ID=1
SZ_DATACENTER_ID=1

# 节点2
SZ_WORKER_ID=2
SZ_DATACENTER_ID=1

# Docker Compose 示例
environment:
  - SZ_WORKER_ID=1
  - SZ_DATACENTER_ID=1

IMPORTANT

workerId 和 datacenterId 的有效范围均为 0 ~ 31，两个节点的 (workerId, datacenterId) 组合必须唯一。

代码生成器生成的代码编译报错怎么办？

代码生成器依赖 MyBatis-Flex 的 APT（注解处理器）在编译时自动生成 xxxDef 类。若生成代码后出现找不到 xxxDef 类的编译错误，执行以下步骤：

Maven 重新编译：mvn clean compile（或在 IDE 中执行 Build → Rebuild Project）
标记生成源码目录：确保 target/generated-sources/annotations 目录被 IDE 识别为源码根目录
若仍报错：检查 sz-dependencies 中 MyBatis-Flex 版本与 APT 处理器版本是否一致。

常见问题 ​

如何查看 OpenAPI 接口文档？ ​

代码报错：xxxDef（包*.table.xxxDef）找不到怎么办？ ​

启动报错：Liquibase changeSet 执行失败怎么办？ ​

启动报错：java.nio.charset.MalformedInputException：Input length = 1怎么办？ ​

如何与官方（上游仓库）代码保持同步？ ​

登陆报错： Cannot read properties of null (reading 'split') ​

项目中的数据库脚本在哪？怎么找不到？ ​

菜单设置了缓存 keep-alive 为什么不生效？ ​

数据权限配置了为什么不生效？ ​

多节点部署时出现主键冲突怎么办？ ​

代码生成器生成的代码编译报错怎么办？ ​

常见问题

如何查看 OpenAPI 接口文档？

代码报错：xxxDef（包*.table.xxxDef）找不到怎么办？

启动报错：Liquibase changeSet 执行失败怎么办？

启动报错：java.nio.charset.MalformedInputException：Input length = 1怎么办？

如何与官方（上游仓库）代码保持同步？

登陆报错： Cannot read properties of null (reading 'split')

项目中的数据库脚本在哪？怎么找不到？

菜单设置了缓存 keep-alive 为什么不生效？

数据权限配置了为什么不生效？

多节点部署时出现主键冲突怎么办？

代码生成器生成的代码编译报错怎么办？