shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

uniapp-springboot-starter

uniapp+springboot开发规则，使智能体在搭建项目时遵循本规则，避免后期大量修改，适合手机+验证码注册和登录的项目，短信验证使用的是火山云，支付使用的是微信支付

personAuthor: Weichen0213hubModelScope
downloadDownload package

uniapp + Spring Boot 全栈开发规范

本 Skill 是一套可执行的全栈项目开发约束。开发时按下方清单逐项落实，详细模板见 references/。

技术栈基线

  • 前端：uniapp 官方最新稳定版（Vue3 + Vite），确保与当前 Spring Boot 版本兼容。
  • 后端：Spring Boot（选择与 uniapp 生态兼容的稳定版，JDK 17+）。
  • 数据库：MySQL 8.x，通过 Flyway 管理版本化迁移。
  • 缓存：Redis（分页缓存、验证码存储、限流）。
  • UI 参考：uView UI（https://uviewui.com）、Vant Weapp（https://vant-ui.github.io/vant-weapp），按需自定义，不强制整套引入。

项目命名与结构

环境变量（最高优先级约束）

  1. 所有可配置项、敏感参数一律走环境变量，代码中不得硬编码。
  2. 根目录维护 .env.example（提交到仓库），实际 .env 加入 .gitignore，不查看、不修改用户的 .env。
  3. MySQL 的 url / username / password 必须从环境变量读取。
  4. 微信支付三端 AppID 分别配置：WX_MINI_APPID、WX_H5_APPID、WX_APP_APPID。
  5. 完整变量清单见 references/env-template.md

Mock / 真实双模式

由环境变量 MOCK 控制：

| MOCK | 行为 | |------|------| | true | 验证码硬编码并前端动态显示（toast/弹窗）、支付走模拟回调、外部服务可短路 | | false | 走真实短信 / 真实微信支付，但万能账号仍可用于线上测试 |

两套代码路径并存，通过配置切换，不通过注释代码切换。

数据库与 Flyway

  • 所有表结构变更通过 src/main/resources/db/migration/V{版本}__{描述}.sql 管理。
  • 禁止手动修改数据库结构。
  • Flyway 集成参考 IDEA 官方文档：https://www.jetbrains.com.cn/help/idea/flyway.html

后端规范

统一响应与异常

  • 所有接口返回 Result<T>，字段：code、message、data。
  • GlobalExceptionHandler 全局捕获异常，业务异常抛 BusinessException，未知异常返回 500 标准结构。
  • 前端据此统一处理，便于联调。

分页 + 缓存

  • 列表接口统一接收 pageNum、pageSize。
  • 热点查询结果缓存到 Redis，缓存 key 包含分页参数和筛选条件 hash。
  • 数据变更时主动清除相关缓存。

复用性

  • 通用 CRUD 抽取 BaseService / BaseMapper。
  • DTO 转换使用 MapStruct 或统一工具类，不手写重复转换。
  • 业务逻辑分层清晰，Controller 只做参数校验和调用 Service。

前端规范

三端适配

  • 使用条件编译 #ifdef MP-WEIXIN / #ifdef H5 / #ifdef APP-PLUS 处理平台差异。
  • 支付、分享、登录等平台相关逻辑封装在 utils/platform.js。

刘海屏 / 顶部安全区

  • 所有页面顶部元素不得从设备刘海开始渲染。
  • 封装 CustomNavBar 组件，通过 uni.getSystemInfoSync() 获取 statusBarHeight，导航栏高度 = 状态栏高度 + 内容区高度。
  • 页面主体使用 padding-top 避开导航栏，主要组件之间不得互相遮盖。
  • 禁止使用原生导航栏 + 自定义顶部元素叠加导致的重叠。

组件化

  • 可复用 UI 必须抽取到 components/：自定义导航栏、验证码输入、空状态、加载更多、底部弹窗等。
  • 组件 props / events 设计通用，不与具体业务耦合。

小程序分包

  • pages.json 中配置 subPackages，主包仅放 tabBar 页面和登录页。
  • 业务模块（订单、支付、设置等）放入分包。
  • 分包规范参考：https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/basic.html

登录体系

手机验证码登录

  • 接口：POST /api/sms/send-code（发送）、POST /api/auth/login（登录）。
  • 验证码存 Redis，TTL 5 分钟，使用后删除。
  • 限流：同手机号 60 秒一次、每天 10 条。

测试环境验证码

  • MOCK=true 时，验证码硬编码（如 123456），后端可在响应中返回 mockCode。
  • 前端点击"获取验证码"后，通过 toast 或弹窗动态显示验证码。
  • 仅测试环境生效。

万能账号（生产环境测试入口）

  • 在 application.yml 中配置 master.phone 和 master.code，支持环境变量覆盖。
  • MASTER_PHONE 留空则禁用。
  • 万能账号在 任何环境包括生产 都可登录，用于线上验证。
  • 登录时先校验万能账号，命中则跳过短信验证码校验，直接签发 token。
  • 日志做特殊标记，便于审计。

退登与注销

  • 必须提供退登接口（清除 token / 加入黑名单）。
  • 必须提供注销账户接口（软删除或匿名化用户数据，清理关联 token）。
  • 注销前二次确认，注销后不可恢复。

短信服务（火山引擎）

  • 使用火山引擎短信 Java SDK 发送验证码。
  • AccessKey / SecretKey / SignID / TemplateID 全部环境变量配置。
  • 详细集成步骤见 references/sms-volcengine.md
  • API 文档：https://docs.volcengine.com/docs/6361/66716
  • Java SDK：https://www.volcengine.com/docs/6361/1109260

微信支付

  • 三端 AppID 分别配置，商户号共用。
  • 后端统一下单接口根据 platform 参数（mini/h5/app）选择对应 AppID。
  • 返回各平台调起支付所需的不同参数格式。
  • 支付回调验签 + 幂等处理。
  • Mock 模式下提供模拟回调接口。
  • 详细适配方案见 references/wechat-pay.md
  • 官方文档：https://pay.weixin.qq.com/doc/v3/merchant/4012062524

测试规范

  1. 执行测试前必须说明测试范围，并确认是否允许测试。
  2. 默认不测试，或仅测试核心功能（登录、支付回调、关键业务流）。
  3. 测试产生的数据在测试完成后必须删除，保持环境干净。
  4. 不使用生产环境数据做测试。

开发检查清单

完成每个模块后逐项确认：

  • [ ] 无硬编码敏感参数，全部走环境变量
  • [ ] .env.example 已更新，.env 未提交
  • [ ] Mock / 真实双模式可通过 MOCK 切换
  • [ ] 数据库变更有对应 Flyway 脚本
  • [ ] 接口返回统一 Result<T>，异常有全局处理
  • [ ] 列表接口有分页 + 缓存
  • [ ] 三端条件编译正确，无平台 API 误用
  • [ ] 顶部元素避开刘海屏，组件间无遮盖
  • [ ] 通用 UI 已组件化
  • [ ] 小程序已配置分包
  • [ ] 登录 / 退登 / 注销功能完整
  • [ ] 万能账号已配置且可用
  • [ ] 微信支付三端下单 + 回调正常
  • [ ] 测试数据已清理