Cursor 开发规范总览按功能维度分享一次使用VibeCoding工具开发一个完整项目后添加的一些规则这些规则并不是Alibaba Java规范 或者 其他什么规范 文件而是实在的项目经验特别说明不承诺可以直接使用其中一些涉及项目名称和敏感数据已进行脱敏处理只作为经验分享如果对项目感兴趣可以浏览SmartShell为运维与研发打造的下一代智能运维工作台总览部署与工程交付拓扑迁移与重启AI 协作流程前端视觉与布局列表与表格交互与权限后端校验与参数SQL 与查询异步与工具类接口输出架构与分层包结构与接口契约目录约定功能领域主要内容架构与分层后端包结构、跨层接口、工程目录划分后端参数校验、SQL 实现、异步线程、JSON/Bean、系统字段、错误键前端页面风格、左树右表、列表交互、权限禁用、确认文案列表与数据分页上限、导入导出、大字段裁剪、Long ID、表头中文数据库与 SQL禁止拼接/IGNORE、Flyway 迁移提示安全与体验重要操作确认、右键菜单视口、前后端校验一致部署与交付Nginx、JAR 加密启动、官网/业务静态资源AI 协作流程本地优先、方案备选、Plan 存放、收尾提示一、架构与分层1.1 后端包结构与职责com.***.dao与单表、资源域强绑定——实体、Mapper、单表 Service 接口与实现。com.***.service跨表、复杂业务流程的应用层 Service。禁止同一业务能力在dao与service各写一套 ServiceImpl。跨层调用Controller → Service、Service → 另一模块对外能力必须依赖接口由 Spring 注入实现类。同层内部私有协作可直接用具体类不强制再抽象接口。1.2 Controller / Service 契约应用层 Service 接口命名、VO/DTO、entities辅助类型放置遵循既有约定。对外响应优先用 VO/DTO 控制字段避免直接暴露实体。1.3 工程目录约定目录用途website/仅官网静态站点HTML、样式、脚本、素材nginx/仅最前端 Nginx 配置反向代理、缓存、HTTPS 模板等frontend/业务工作台 SPAbackend/Spring Boot API 与领域逻辑.cursor/plans/可执行迭代 Plan不放docs/作唯一副本二、后端2.1 参数与校验方法参数尽量不超过5 个超出时封装为 Bean/VO/DTO。Controller 入参统一用Validate 注解Validated、Valid、NotBlank等禁止在方法体内手工判空。每个约束必须带message优先使用MessageConstant的ERR_*键。业务「记录不存在」等可保留业务异常基础格式/必填校验不走if分支。2.2 SQL 与数据访问禁止在 Java 中拼接 SQL含wrapper.apply、last内嵌片段。业务查询、分页、筛选下沉Mapper XML参数一律#{}预编译绑定。${}仅用于结构位且可白名单约束的场景如固定排序字段映射。发现存量 Java 内 SQL 片段优先迁移到 XML并保持语义一致。2.3 异步与并发禁止new Thread(...)及在业务类中Executors.new*建池。线程池在config下集中声明 Bean名称使用AsyncExecutorConstant。Async必须显式指定线程池名定时/延迟任务注入已注册的ScheduledExecutorServiceBean。2.4 工具类与传值类型JSON 转换优先JsonUtil不足时在其上扩展不引入新 JSON 库。请求/响应传值使用普通class Bean禁止public record。2.5 接口输出与系统字段以下字段为系统字段对外列表/详情/分页默认不返回remark、isDeleted、tenantId前端不得将其作为业务展示字段依赖确需透出须在接口注释标明「系统字段透出」。2.6 错误与文案后端业务异常优先返回稳定ERR_*键不写死自然语言提示。前端在errorMessageMap.js映射展示文案页面提示由前端实现。2.7 列表查询性能后端侧分页列表不 SELECTTEXT/LONGTEXT 及与展示无关的超大 VARCHAR约1000 字符视为大字段。完整内容通过详情接口按主键 ID单独查询。导出如需大字段使用专用导出 SQL与列表分页 SQL 分离。2.8 分页与导入导出后端侧全局分页pageSize最大 1000。导入条数、文件大小受sys_property系统参数约束默认 100 条 / 10MB。导出强约束最多1000 条。初始化参数变更合并到V2__add_init_data.sql开发阶段不做向前兼容旧数据迁移。2.9 缓存模块缓存相关代码已人为调整以当前工作区实现为基线。修改前必须先读取最新文件不得恢复已移除能力或擅自改变 API 契约。2.10 加密与 Spring 扫描mvn package对com.haiwei/service核心类加密是正当需求。不以「跳过加密」作为默认方案来回避 Spring 组件扫描问题须从启动链路与扫描配置正面解决。三、前端3.1 视觉与品牌基调整体风格安全、智能、科技、商务、正式。中低饱和、稳重配色强调信息用品牌蓝/科技青危险操作用克制风险色。按钮、卡片、表格、弹窗圆角、轻阴影、清晰边界、可读性优先。主按钮文字对比度充足操作区命名简洁一致如「导入/导出」。3.2 布局左树右表左侧树/筛选 右侧主内容的分栏页必须支持拖拽调宽col-resize手柄最小/最大宽度限制。左树容器、右侧列表卡片、分隔条样式在同类页面保持一致。搜索区、筛选摘要、按钮摆放、表格表头/行 hover、分页区对齐标杆页Linux 资源、用户管理等。3.3 列表页通用能力标杆参考布局与筛选LinuxResource.vue页头统计、搜索栏、当前筛选摘要列配置、折叠搜索、导出OperationLog.vue搜索区与主表视觉User.vue 根节点 classlist-page-unifiedlist-page-unified.css必须具备的能力能力要求页头统计当前页条数、已选、符合条件总数等搜索栏与标杆页一致的query-form布局搜索按钮带图标筛选摘要有条件时展示「当前筛选」 清空入口列配置操作列齿轮显隐、拖拽排序、列宽持久化到 DB表头拖拽整段列名可拖排序与列配置一致并持久化折叠搜索显隐列旁切换隐藏页头/搜索/筛选摘要以扩大表格区操作列按钮带图标高频靠前危险与低频进「更多」「更多」入口统一图标与同行动按钮垂直/水平对齐表头中文可配置列表默认简体中文文案分层到常量/工具文件3.4 导入导出前端侧导入弹窗 文件选择 CSV/Excel 模板下载须先展示预检查结果新增/更新/异常/超限再允许提交。导出弹窗选择「导出选中」或「导出符合条件前 1000 条」 文件类型展示已选条数与上限未选中时阻止「导出选中」。3.5 权限与按钮绑定button:*权限的按钮、行内操作、「更多」下拉项、弹窗确定/保存渲染时即v-perm-disable disabled。禁止可点击后才因 403 或保存失败首次提示无权限。3.6 重要操作确认适用于删除、撤销授权、状态变更、SSH/数据库连接登录等。确认文案须包含操作对象主标识推荐书名号确认删除用户组「xxx」。禁止仅写「确认删除该 xxx」等无对象文案。批量操作至少展示条数单条须展示主标识可列举前 13 条摘要。连接类操作在确认区展示连接摘要资源名、IP/主机、端口、凭据用户、操作类型等不展示密码。推荐使用confirmTargetLabel处理过长名称。3.7 右键与上下文菜单position: fixed自定义菜单含 Teleport、标签页右键、DB 控制台等须完整落在视口内。使用scheduleClampFixedMenuclampFixedMenuToViewport.jsnextTick 双requestAnimationFrame测量修正。样式兜底max-height/width: calc(100vh/vw - 16px)项多内部滚动。3.8 前后端校验一致VO 新增的长度、正则、必填等约束前端提交前须做同等或更严校验。新增ERR_*键须同步errorMessageMap.js。四、前后端共通4.1 Long / 雪花 ID 精度后端Long/BIGINT序列化为 JSON字符串JacksonConfig 可选JsonSerialize。前端禁止对大 ID 使用Number()/parseIntid、parentId、树/下拉 value 统一String(...)。提交后端顶层0可用数字非 0 的 Long 字段用字符串避免JSON.stringify前精度丢失。el-tree-select的 value 与v-model类型须一致通常为string。4.2 列表大字段策略全栈列表分页 ──► 裁剪字段 / 预览截断 │ ├─► 详情弹窗 ──► GET /{id} 拉完整内容 └─► 导出 ──► 专用全列 SQL可与列表 SQL 分离已落地示例操作日志、SQL 执行日志管理端列表。五、数据库与 SQL5.1 INSERT 规范禁止INSERT IGNORE及等价「忽略错误」写法。使用普通INSERT让主键/唯一/非空/外键违反时立即报错。幂等需求用WHERE NOT EXISTS、拆分迁移版本等显式设计不靠 IGNORE 掩盖。5.2 迁移与本地库迁移脚本目录backend/src/main/resources/db/migration/开发阶段初始化数据合并V2__add_init_data.sql修改库结构或初始化 SQL 后须在任务收尾提醒本地库需通过Flyway或常用迁移方式重新执行/校验。六、部署与交付6.1 典型拓扑最前层Nginx或等价反向代理→ 容器/进程承载业务与站点。业务系统管理端前端 API与官网可拆分部署。使用本仓库build/Dockerfile时官网可在站点根/业务 SPA 常在子路径如/***/。6.2 交付单元后端统一为可执行Spring Boot JAR容器化时在 JAR 外包 Docker。内置流程ClassEncryptor加密 → Manifest 主类SecureLauncher→ 运行时解密启动Application。变更加密/启动链须同步docs/部署方案.md。6.3 静态资源落点官网源码website/与 JAR 一体交付时可输出到backend/src/main/resources/static/。业务前端 Vite 默认outDir也指向static/官网与业务 SPA 同时打进同一 JAR 时须明确构建顺序与base避免互相覆盖。七、AI 协作与研发流程7.1 以工作区为准用户声明「本地已改 / 以本地为准」时工作区源码优先于历史对话、过时文档或规则中的旧表述。改pom.xml、启动类、加密相关代码前必须先Read真实文件。7.2 方案与备选编码、选型、设计时若存在更稳妥/可维护/更安全做法须主动说明备选与权衡由用户决策。即使用户已指定技术栈仍应简要给出风险或更优路径如有。7.3 任务收尾提示场景是否提示重启/重跑application.yml、pom.xml、Flyway 新迁移、vite.config.js等非 HMR 配置需要纯 Vue/CSS/普通业务 Java热更新或自动重启不需要例行提示仅文档/注释/格式化不需要7.4 文档分工类型存放位置可执行迭代 Plan.cursor/plans/正式架构、部署、环境变量docs/Cursor 规范摘要本文档八、自检清单按角色后端开发跨层注入接口单表在 dao、复杂业务在 serviceController VO 校验带messageERR_*查询在 Mapper XML无 Java SQL 拼接列表 SQL 不含大字段有独立详情查询分页/导出 ≤1000无INSERT IGNORE系统字段默认不出现在对外 VO异步走统一线程池前端开发页面风格与标杆列表一致左树右表可拖拽标准列表具备列配置、折叠搜索、筛选摘要「更多」为无权限前置 disabled删除/撤销等 confirm 含对象主标识大 ID 全程字符串树/select value 类型一致导入导出走弹窗 预检查/条数提示自定义右键菜单已做视口夹紧全栈 / 运维改 SQL 后提醒 Flyway改部署/加密链同步docs/部署方案.mdwebsite/nginx目录未混放业务代码维护说明新增或调整开发约束时按功能章节更新本文档而非堆砌规则文件名。与docs/技术架构.md冲突时以工作区代码 正式架构文档为准本文档侧重日常协作速查。新工程初始化可复制docs/Cursor规则初始化模板.md与docs/cursor-rule-templates/下的通用模板。
从0到1完整开发Smartshell最后沉淀出的Cursor开发规则
Cursor 开发规范总览按功能维度分享一次使用VibeCoding工具开发一个完整项目后添加的一些规则这些规则并不是Alibaba Java规范 或者 其他什么规范 文件而是实在的项目经验特别说明不承诺可以直接使用其中一些涉及项目名称和敏感数据已进行脱敏处理只作为经验分享如果对项目感兴趣可以浏览SmartShell为运维与研发打造的下一代智能运维工作台总览部署与工程交付拓扑迁移与重启AI 协作流程前端视觉与布局列表与表格交互与权限后端校验与参数SQL 与查询异步与工具类接口输出架构与分层包结构与接口契约目录约定功能领域主要内容架构与分层后端包结构、跨层接口、工程目录划分后端参数校验、SQL 实现、异步线程、JSON/Bean、系统字段、错误键前端页面风格、左树右表、列表交互、权限禁用、确认文案列表与数据分页上限、导入导出、大字段裁剪、Long ID、表头中文数据库与 SQL禁止拼接/IGNORE、Flyway 迁移提示安全与体验重要操作确认、右键菜单视口、前后端校验一致部署与交付Nginx、JAR 加密启动、官网/业务静态资源AI 协作流程本地优先、方案备选、Plan 存放、收尾提示一、架构与分层1.1 后端包结构与职责com.***.dao与单表、资源域强绑定——实体、Mapper、单表 Service 接口与实现。com.***.service跨表、复杂业务流程的应用层 Service。禁止同一业务能力在dao与service各写一套 ServiceImpl。跨层调用Controller → Service、Service → 另一模块对外能力必须依赖接口由 Spring 注入实现类。同层内部私有协作可直接用具体类不强制再抽象接口。1.2 Controller / Service 契约应用层 Service 接口命名、VO/DTO、entities辅助类型放置遵循既有约定。对外响应优先用 VO/DTO 控制字段避免直接暴露实体。1.3 工程目录约定目录用途website/仅官网静态站点HTML、样式、脚本、素材nginx/仅最前端 Nginx 配置反向代理、缓存、HTTPS 模板等frontend/业务工作台 SPAbackend/Spring Boot API 与领域逻辑.cursor/plans/可执行迭代 Plan不放docs/作唯一副本二、后端2.1 参数与校验方法参数尽量不超过5 个超出时封装为 Bean/VO/DTO。Controller 入参统一用Validate 注解Validated、Valid、NotBlank等禁止在方法体内手工判空。每个约束必须带message优先使用MessageConstant的ERR_*键。业务「记录不存在」等可保留业务异常基础格式/必填校验不走if分支。2.2 SQL 与数据访问禁止在 Java 中拼接 SQL含wrapper.apply、last内嵌片段。业务查询、分页、筛选下沉Mapper XML参数一律#{}预编译绑定。${}仅用于结构位且可白名单约束的场景如固定排序字段映射。发现存量 Java 内 SQL 片段优先迁移到 XML并保持语义一致。2.3 异步与并发禁止new Thread(...)及在业务类中Executors.new*建池。线程池在config下集中声明 Bean名称使用AsyncExecutorConstant。Async必须显式指定线程池名定时/延迟任务注入已注册的ScheduledExecutorServiceBean。2.4 工具类与传值类型JSON 转换优先JsonUtil不足时在其上扩展不引入新 JSON 库。请求/响应传值使用普通class Bean禁止public record。2.5 接口输出与系统字段以下字段为系统字段对外列表/详情/分页默认不返回remark、isDeleted、tenantId前端不得将其作为业务展示字段依赖确需透出须在接口注释标明「系统字段透出」。2.6 错误与文案后端业务异常优先返回稳定ERR_*键不写死自然语言提示。前端在errorMessageMap.js映射展示文案页面提示由前端实现。2.7 列表查询性能后端侧分页列表不 SELECTTEXT/LONGTEXT 及与展示无关的超大 VARCHAR约1000 字符视为大字段。完整内容通过详情接口按主键 ID单独查询。导出如需大字段使用专用导出 SQL与列表分页 SQL 分离。2.8 分页与导入导出后端侧全局分页pageSize最大 1000。导入条数、文件大小受sys_property系统参数约束默认 100 条 / 10MB。导出强约束最多1000 条。初始化参数变更合并到V2__add_init_data.sql开发阶段不做向前兼容旧数据迁移。2.9 缓存模块缓存相关代码已人为调整以当前工作区实现为基线。修改前必须先读取最新文件不得恢复已移除能力或擅自改变 API 契约。2.10 加密与 Spring 扫描mvn package对com.haiwei/service核心类加密是正当需求。不以「跳过加密」作为默认方案来回避 Spring 组件扫描问题须从启动链路与扫描配置正面解决。三、前端3.1 视觉与品牌基调整体风格安全、智能、科技、商务、正式。中低饱和、稳重配色强调信息用品牌蓝/科技青危险操作用克制风险色。按钮、卡片、表格、弹窗圆角、轻阴影、清晰边界、可读性优先。主按钮文字对比度充足操作区命名简洁一致如「导入/导出」。3.2 布局左树右表左侧树/筛选 右侧主内容的分栏页必须支持拖拽调宽col-resize手柄最小/最大宽度限制。左树容器、右侧列表卡片、分隔条样式在同类页面保持一致。搜索区、筛选摘要、按钮摆放、表格表头/行 hover、分页区对齐标杆页Linux 资源、用户管理等。3.3 列表页通用能力标杆参考布局与筛选LinuxResource.vue页头统计、搜索栏、当前筛选摘要列配置、折叠搜索、导出OperationLog.vue搜索区与主表视觉User.vue 根节点 classlist-page-unifiedlist-page-unified.css必须具备的能力能力要求页头统计当前页条数、已选、符合条件总数等搜索栏与标杆页一致的query-form布局搜索按钮带图标筛选摘要有条件时展示「当前筛选」 清空入口列配置操作列齿轮显隐、拖拽排序、列宽持久化到 DB表头拖拽整段列名可拖排序与列配置一致并持久化折叠搜索显隐列旁切换隐藏页头/搜索/筛选摘要以扩大表格区操作列按钮带图标高频靠前危险与低频进「更多」「更多」入口统一图标与同行动按钮垂直/水平对齐表头中文可配置列表默认简体中文文案分层到常量/工具文件3.4 导入导出前端侧导入弹窗 文件选择 CSV/Excel 模板下载须先展示预检查结果新增/更新/异常/超限再允许提交。导出弹窗选择「导出选中」或「导出符合条件前 1000 条」 文件类型展示已选条数与上限未选中时阻止「导出选中」。3.5 权限与按钮绑定button:*权限的按钮、行内操作、「更多」下拉项、弹窗确定/保存渲染时即v-perm-disable disabled。禁止可点击后才因 403 或保存失败首次提示无权限。3.6 重要操作确认适用于删除、撤销授权、状态变更、SSH/数据库连接登录等。确认文案须包含操作对象主标识推荐书名号确认删除用户组「xxx」。禁止仅写「确认删除该 xxx」等无对象文案。批量操作至少展示条数单条须展示主标识可列举前 13 条摘要。连接类操作在确认区展示连接摘要资源名、IP/主机、端口、凭据用户、操作类型等不展示密码。推荐使用confirmTargetLabel处理过长名称。3.7 右键与上下文菜单position: fixed自定义菜单含 Teleport、标签页右键、DB 控制台等须完整落在视口内。使用scheduleClampFixedMenuclampFixedMenuToViewport.jsnextTick 双requestAnimationFrame测量修正。样式兜底max-height/width: calc(100vh/vw - 16px)项多内部滚动。3.8 前后端校验一致VO 新增的长度、正则、必填等约束前端提交前须做同等或更严校验。新增ERR_*键须同步errorMessageMap.js。四、前后端共通4.1 Long / 雪花 ID 精度后端Long/BIGINT序列化为 JSON字符串JacksonConfig 可选JsonSerialize。前端禁止对大 ID 使用Number()/parseIntid、parentId、树/下拉 value 统一String(...)。提交后端顶层0可用数字非 0 的 Long 字段用字符串避免JSON.stringify前精度丢失。el-tree-select的 value 与v-model类型须一致通常为string。4.2 列表大字段策略全栈列表分页 ──► 裁剪字段 / 预览截断 │ ├─► 详情弹窗 ──► GET /{id} 拉完整内容 └─► 导出 ──► 专用全列 SQL可与列表 SQL 分离已落地示例操作日志、SQL 执行日志管理端列表。五、数据库与 SQL5.1 INSERT 规范禁止INSERT IGNORE及等价「忽略错误」写法。使用普通INSERT让主键/唯一/非空/外键违反时立即报错。幂等需求用WHERE NOT EXISTS、拆分迁移版本等显式设计不靠 IGNORE 掩盖。5.2 迁移与本地库迁移脚本目录backend/src/main/resources/db/migration/开发阶段初始化数据合并V2__add_init_data.sql修改库结构或初始化 SQL 后须在任务收尾提醒本地库需通过Flyway或常用迁移方式重新执行/校验。六、部署与交付6.1 典型拓扑最前层Nginx或等价反向代理→ 容器/进程承载业务与站点。业务系统管理端前端 API与官网可拆分部署。使用本仓库build/Dockerfile时官网可在站点根/业务 SPA 常在子路径如/***/。6.2 交付单元后端统一为可执行Spring Boot JAR容器化时在 JAR 外包 Docker。内置流程ClassEncryptor加密 → Manifest 主类SecureLauncher→ 运行时解密启动Application。变更加密/启动链须同步docs/部署方案.md。6.3 静态资源落点官网源码website/与 JAR 一体交付时可输出到backend/src/main/resources/static/。业务前端 Vite 默认outDir也指向static/官网与业务 SPA 同时打进同一 JAR 时须明确构建顺序与base避免互相覆盖。七、AI 协作与研发流程7.1 以工作区为准用户声明「本地已改 / 以本地为准」时工作区源码优先于历史对话、过时文档或规则中的旧表述。改pom.xml、启动类、加密相关代码前必须先Read真实文件。7.2 方案与备选编码、选型、设计时若存在更稳妥/可维护/更安全做法须主动说明备选与权衡由用户决策。即使用户已指定技术栈仍应简要给出风险或更优路径如有。7.3 任务收尾提示场景是否提示重启/重跑application.yml、pom.xml、Flyway 新迁移、vite.config.js等非 HMR 配置需要纯 Vue/CSS/普通业务 Java热更新或自动重启不需要例行提示仅文档/注释/格式化不需要7.4 文档分工类型存放位置可执行迭代 Plan.cursor/plans/正式架构、部署、环境变量docs/Cursor 规范摘要本文档八、自检清单按角色后端开发跨层注入接口单表在 dao、复杂业务在 serviceController VO 校验带messageERR_*查询在 Mapper XML无 Java SQL 拼接列表 SQL 不含大字段有独立详情查询分页/导出 ≤1000无INSERT IGNORE系统字段默认不出现在对外 VO异步走统一线程池前端开发页面风格与标杆列表一致左树右表可拖拽标准列表具备列配置、折叠搜索、筛选摘要「更多」为无权限前置 disabled删除/撤销等 confirm 含对象主标识大 ID 全程字符串树/select value 类型一致导入导出走弹窗 预检查/条数提示自定义右键菜单已做视口夹紧全栈 / 运维改 SQL 后提醒 Flyway改部署/加密链同步docs/部署方案.mdwebsite/nginx目录未混放业务代码维护说明新增或调整开发约束时按功能章节更新本文档而非堆砌规则文件名。与docs/技术架构.md冲突时以工作区代码 正式架构文档为准本文档侧重日常协作速查。新工程初始化可复制docs/Cursor规则初始化模板.md与docs/cursor-rule-templates/下的通用模板。
