注意事项与踩坑

作者: luote (luote) · 个人主页 luote996.cn

二次开发时最容易出问题的点，建议发布前逐项检查。

环境与配置

后端 .env 不会自动加载

Spring Boot 默认不读 .env 文件。开发时可选方案：

• IDE 安装 EnvFile 插件，运行配置指向 .env
• Docker Compose 注入环境变量
• 系统环境变量 export

前端代理

开发环境 vite.config.ts 已将 /api 代理到后端。.env.development 中：

VITE_API_BASE_URL=/api
VITE_API_PROXY_TARGET=http://localhost:8080

如果接口 404，先检查：

1. 后端是否启动在 8080
2. VITE_API_PROXY_TARGET 是否正确
3. 后端 Controller 路径是否以 /api 开头（看 application.yml 的 context-path）

改 env 后需重启

• 后端改 .env：重启 Spring Boot
• 前端改 .env.development：重启 npm run dev

后端开发注意

异常处理

业务错误用 BusinessException，不要直接 throw new RuntimeException：

throw new BusinessException(ExceptionConstant.USER_NOT_FOUND);

全局异常处理器会统一返回 JSON，前端能正常弹提示。

参数校验

Controller 方法参数加校验注解：

@NotBlank @Size(max = 64) String title

DTO 类加 @Valid，Controller 参数加 @Valid @RequestBody。

分页上限

分页 size 最大 100，超过会被校验拦截。不要在前端传超大分页。

软删除

po 类使用 @TableLogic 标记 deleted 字段。调用 removeById 时是逻辑删除，不是物理删除。

密码字段

User 的 password 不会出现在 VO 中。新增用户时 Service 层用 BCryptPasswordEncoder 加密，不要明文存库。

Swagger 测试要带 Token

除登录、注册、验证码外，接口都需要 JWT。Swagger 中先 Authorize 再测试。

包名和扫描

新建类放在 cn.luote 包下即可，启动类 @SpringBootApplication 会自动扫描子包。

前端开发注意

request 已解包 data

request.get/post 返回的是 data 字段，不是完整 Result：

// 正确
const user = await getCurrentUser()

// 错误，不需要再 .data
const user = await getCurrentUser().data

Token 存储

Token 存在 localStorage，request.ts 请求拦截器自动附加。401 时自动清 Token 并跳转登录页。

路由 meta.public

登录页、注册页必须设 meta: { public: true }，否则未登录无法访问。

新页面默认需要登录，不加 public 即可。

页面目录规范

每个模块一个文件夹，入口文件固定 index.vue：

view/
  notice/
    index.vue
  order/
    index.vue

不要用假数据上线

首页已改为空状态。业务数据请接真实接口，不要在模板里写死测试数据。

安全相关

生产环境必改项

配置	说明
JWT_SECRET	改为长随机字符串
DB_PASSWORD	改为强密码
admin 默认密码	首次部署后立即修改
CORS_ORIGINS	改为正式前端域名
AI_DASHSCOPE_API_KEY	填入真实 Key

权限

• 管理类接口加 @PreAuthorize("hasRole('ADMIN')")
• 普通用户接口在 Service 层校验 UserContext.getUserId() 是否为数据所有者

不要提交敏感文件

.env、数据库密码、API Key 不要提交 Git。模板只保留 .env.example。

常见报错排查

现象	可能原因	处理
验证码不显示	后端未启动或 Redis 未启动	检查后端日志
401 未授权	Token 过期或未带 Token	重新登录
403 禁止访问	角色不够	用 admin 账号或调整权限
CORS 错误	跨域白名单未配置	检查 CORS_ORIGINS
前端接口 404	代理或路径错误	检查 VITE_API_BASE_URL 和后端路径
MyBatis 表不存在	未执行 data.sql	手动建表
端口占用	8080 或 5173 被占	改 .env 端口或关闭占用进程

推荐开发习惯

1. 先后端后前端：Swagger 通了再写页面
2. 小步提交：一个接口一个接口做，不要一次改太多
3. 复制改比从零写快：用户模块是最好的模板
4. 看日志：后端看控制台，前端看浏览器 Network 和 Console
5. 改表先备份：生产环境改数据库前先备份

学习路径建议（0 基础）

阶段	学什么	目标
1	跑通项目	能登录、看到首页
2	读懂用户模块	理解 Controller → Service → Mapper
3	照抄做一个模块	完成 notice 或自己的业务
4	改页面和交互	学会 Element Plus 表格、表单
5	加权限和校验	理解 JWT、RBAC、参数校验

遇到具体问题，优先查 Swagger 和后端日志，再查浏览器 Network 面板。