AI全栈开发最佳实践💐

大家好，我是前端小张同学，今天给大家分享一下写AI代码的思路，最近也是天天在用AI写代码，感觉自己手写代码的能力已经下降了很多，不过按照这个节奏AI写代码必定替代人工在各种场景下，话不多说，以我这个最近的给自己搭建的一个数字分身系统为例。

1：如何用AI开始并写出来的代码是理想状态下的。

1：很多人以为AI只是停留在辅助阶段，只能帮你改改问题或者改改部分代码，那你就大错特错了，2026年使用AI编程的人数大幅提升，如果你还停留在手动敲代码阶段，你可得注意了。

2：AI能干的事情远不止于帮你修修补补，现在随着智能体的发展，AI的工程化能力也是越来越强大，你应该引导如何让它帮助你从0-1搭建一个系统，你需要有系统性的思维，怎么做呢？先推荐大家看一个架构思维网站。

1.1 我的思路

我开发一个应用我会做以下几件事情

确认系统方向 ：系统的大致方向确认，比如数字分身系统，这个系统要解决什么问题，它和一些传统的系统有什么区别，你自己方向得把握好，当然如果你们公司有明确的需求文档那你不必担心这种问题。
讨论系统的功能：，定功能方向，有人问，这我怎么定，我不会啊，不会就对了，就你代码水平可能很高，但产品思维你不一定，那谁能充当产品经理？那当然是AI，把你的想法和AI进行多轮交流，你慢慢的脑子里就有画面了。
需求文档确认：想法兑现，这一步，你的想法与AI多轮互动后，再输出一份文档你开始兑奖了，看看最终的需求文档是不是你想要的，理想中的系统。
设计稿：如果你实在想不到，那我建议你做这一步，让AI按照需求文档功能模块帮你生成一下你的系统的大致的架构样子，这样我相信你思路会更清晰了。
架构设计 ：关键点来了，需求你自己搞定了，架构设计尤为重要，先说简单的系统，如果你不涉及到高并发，熔断，限流，订单支付，超时，这种一系列的场景，那很好办，你的关键考虑点在以下几个方面。

简单系统

系统的数据库设计，底层表结构。
是否需要用到一些中间件，redis，MQ，es搜索引擎？他们有没有什么特殊场景用到
后端及前端的工程化体系设计？单体服务，日志，响应，环境配置，模块划分，是否用mp，分页如何实现。
鉴权，通过什么方式？
前端系统，工程化 eslint，stylelint，vue全家桶，或者react，包管理器用什么，请求如何封装。

差不多一个简单系统这些已经就够用了。

复杂系统

如果是复杂系统，我相信这个也不会让你一个人来做的，除非你们是一人公司，复杂系统考虑也是和上面思路差不多，无非是你需要挖的更细，比如支付这块，你的订单已经支付成功了，但是接收微信返回的消息时候，服务器宕机，你怎么处理，支付支持哪几种模式，余额？微信？支付宝，消息队列重复消费？ redis的缓存。等等，实话实说，小张同学现在的能力还没达到那种能自己架构一个完整的企业复杂系统，只能说大致的方向是有的，我还得学习，加油！✌️✌️。

1.2：skill规范很关键

一个skill规范决定了你代码开始的质量，如果你一开始代码就没有规范，全靠AI生成，这样的代码你后期维护难度将会会非常的高，因为我用AI编码的过程中发现一个问题，比如AI他是不会管你工具类的，也不会管你有些方法有没有封装复用，它的逻辑是帮你完成任务，如果出现要封装的直接自己重复造轮子，包括代码如果你不约束三层架构，前端不约束代码写在哪个目录里他就会一顿给你开始乱写，最后写完发现你自己都看不懂，所以 skill规范很重要，我总结出了两套规范，一套是前端的一套是后端的，下面这个大家看个大概，我后面把它传到github上。

前端

markdown 复制代码

---
name: vue-typescript-development
description: >-
  Applies Vue 3 + TypeScript frontend quality, security, architecture, and API
  contract standards for SPAs and admin dashboards. Use when writing or reviewing
  Vue/TS/SFC code, composables, api modules, forms, uploads, routing, styling,
  Less/CSS, or when the user mentions 前端规范、Vue 规范、TypeScript、Less、样式、
  目录分层、接口契约、质量下限.
---

# Vue 3 + TypeScript 开发规范

## 何时启用

- 新建/修改 **Vue 3 + TypeScript** 前端（中后台、看板、SDK 管理端等）
- Code Review、重构、联调接口、权限/表单/上传相关改动
- 用户要求按团队前端规范交付，且未指定更窄 scope 时

## 执行顺序（必须）

1. **读仓库 `README.md`**：接口成功码、环境变量、上传限制、lint 命令 --- **以 README 为契约事实来源**
2. **读项目级 Cursor Rule**（若有，如 `essence-admin-vue3.mdc`）：业务域路径、UI 模板、仓库专属约定
3. **按 [reference.md](reference.md) 执行**；冲突时取 **更严** 者

## 核心纪律（摘要）

| 领域 | 要点 |
|------|------|
| 分层 | `api/` 仅 HTTP；页面 → api/hooks/components；禁止 utils → views |
| 接口 | 禁止猜 `res.list`/`res.data`；先按 README + 拦截器判定成功 |
| 类型 | 默认禁止 `any`；禁止未判空访问嵌套属性 |
| 模板 | 禁止同元素 `v-if`+`v-for`；`v-for` 须稳定 `:key` |
| 写操作 | loading + 防重复提交；路由/query 输入须校验 |
| 安全 | 密钥不进源码；日志不上报 token/PII；`redirect` 须白名单 |
| 样式 | **Less** 预处理；SFC 用 `lang="less" scoped`；token 进 `styles/variables.less` |
| 体量 | 单函数建议 ≤80 行；单 `.vue` 警戒 400 行；先 composable 再拆子组件 |

## 反例（禁止）

```ts
const res = await api.getList()
const list = Array.isArray(res) ? res : (res?.list ?? res?.data ?? [])
```

应先理解 README 与拦截器 unwrap 语义，再读取并校验载荷。

## 交付前

走 [checklist.md](checklist.md) 自检；完整条文见 [reference.md](reference.md)。

## 维护同步

规范正文维护在 `.cursor/skills/vue-typescript-development/reference.md`。  
跨项目个人目录同步：在仓库根目录执行 `pnpm sync:vue-skill`。

后端

yaml 复制代码

---
name: java-modular-monolith
description: >-
  Guides scaffolding and daily coding of a Java Spring Boot modular monolith:
  Maven BOM, framework starters, server shell, api/biz modules, three API channels,
  Controller/Service/Mapper layering, specific ErrorCode per failure, logging, and
  config governance. Use when creating a new backend, adding a module or API,
  reviewing architecture, copying conventions to another project, or when the user
  mentions 单体架构、模块化单体、搭建框架、工程规范、代码规范.
---

# Java 模块化单体规范（通用）

规定 **怎么搭框架、怎么写代码**，不绑定具体业务域。占位符见下表，先读仓库绑定再替换。

| 任务 | 先读 |
|------|------|
| 从零搭工程 / 迁框架 | [scaffolding.md](scaffolding.md) |
| 新模块 / 新 CRUD / 日常编码 | [coding.md](coding.md) |
| 日志、配置、开放对接、框架类型 | [reference.md](reference.md) |
| 自检 / Review | [checklist.md](checklist.md) |
| 复制到其它仓库 | [adapt.md](adapt.md) |

当前仓库若有「项目绑定」Skill（如 `*-architecture-standards`），**先读其占位表**，再套用本文。

---

## 1. 何时启用

- 新建 Spring Boot 后端、拆模块、加 Starter、加开放通道
- 新管理端 / C 端 / 外部接口，或 Code Review 分层与错误码
- 把本规范迁到另一个工程
- 用户提到：单体架构、模块化单体、搭建框架、工程规范、api/biz

不用于：纯业务字段含义、前端 Vue、具体表设计讨论（除非同时改后端分层）。

---

## 2. 占位符

| 占位 | 含义 | 示例 |
|------|------|------|
| `{app}` | 工程前缀（Maven artifact / YAML 根） | `acme` |
| `{base}` | Java 根包 | `co.example.acme` |
| `{domain}` | 业务域 | `order` |
| `{resource}` | 资源（URL 与类名） | `store-order` / `StoreOrder` |
| `{admin-prefix}` | 管理端 URL 前缀 | `/admin-api` |
| `{app-prefix}` | C 端 URL 前缀 | `/app-api` |

复制到新工程时只改这些值，目录形态不变。

---

## 3. 架构决策（必须遵守）

**形态**：一个 JVM、一个可执行 JAR。`{app}-server` 聚合各 `*-biz`；横切能力进 `{app}-framework`。

```text
{app}-server          启动壳：依赖 *-biz + application*.yaml
     │
     ├─ {app}-module-{domain}-biz     实现
     │        └── 依赖 → {app}-module-{domain}-api   契约
     ├─ {app}-framework               Starter 平台
     └─ {app}-dependencies            BOM
```

| 决策 | 意图 | 禁止 |
|------|------|------|
| 模块化单体 | 运维简单、本地事务 | 把模块当微服务乱加 RPC |
| api / biz 分离 | 跨模块只依赖契约 | biz 依赖另一模块的 biz |
| Starter 平台化 | 横切可复制 | 业务代码进 framework |
| 包路径驱动 URL | 约定优于配置 | Controller 手写 `{admin-prefix}` |
| 配置跟域走 | 启动类保持空 | 启动类堆 `@EnableConfigurationProperties` |

**一句话**：Server 是容器，Framework 是平台，Module 是插件。

---

## 4. 设计原则

| 原则 | 说明 |
|------|------|
| 契约与实现分离 | 跨模块只暴露 `*-api`（ErrorCode、enum、DTO） |
| 单向依赖 | Controller → Service → Mapper |
| 框架与业务解耦 | 通用进 framework，业务进 `module-*` |
| 接口分通道 | 管理端 / C 端 / 外部对接，鉴权隔离 |
| 统一契约 | `CommonResult`、ErrorCode、VO 命名一致 |
| 具体错误具体消息 | 每种失败独立 ErrorCode；禁止运行时拼 msg |

---

## 5. 按任务执行

**从零搭框架 / 裁剪复制框架** → [scaffolding.md](scaffolding.md)

1. 定占位符与技术栈  
2. 建 BOM → framework 最小集 → server 空壳  
3. 第一个 `module-{domain}`（api + biz）跑通一条管理端 CRUD  
4. 需要再加 security / redis / job；开放通道按 7 步加  

**新业务模块** → [scaffolding.md](scaffolding.md)「新模块」+ [coding.md](coding.md)

1. 父 POM 声明 `{app}-module-{domain}`（其下 api + biz）  
2. api：ErrorCode 段 + enum  
3. biz：dal → convert → service → controller  
4. **只改 server 的 pom 引入 `*-biz`**，不改启动类业务逻辑  

**新管理端 / C 端接口** → [coding.md](coding.md) → [checklist.md](checklist.md)

**新开放接口** → [reference.md](reference.md)「外部对接 7 步」

**Review / PR** → [checklist.md](checklist.md)

**迁到其它工程** → [adapt.md](adapt.md)

---

## 6. 工程与模块（摘要）

```text
{root}/
├── {app}-dependencies/
├── {app}-framework/
│   ├── {app}-common/
│   └── {app}-spring-boot-starter-{web|security|mybatis|...}/
├── {app}-server/
└── {app}-module-{domain}/
    ├── {app}-module-{domain}-api/
    └── {app}-module-{domain}-biz/
```

**基线栈**：Java 17 · Spring Boot 3.x · Maven · MyBatis-Plus · MapStruct · Redis · Spring Security

**api 只放**：ErrorCode、enums、跨模块 DTO（无 Controller / 无 Spring Web）  
**biz 只放**：Controller、ServiceImpl、DO、Mapper、Convert、域内 Filter / Configuration

跨 **2+ 模块** 才抽 `XxxApi` + `XxxApiImpl`；同 JVM 不必 RPC 化。

---

## 7. 三通道（安全架构）

| 通道 | 包 | URL | 鉴权 |
|------|-----|-----|------|
| 管理端 | `controller.admin.*` | `/{domain}/{resource}` | Token + `@PreAuthorize` |
| C 端 | `controller.app.*` | 模块约定 | 用户 Token |
| 外部 | `controller.{开放名}` | `/external/{系统}` | **独立 Filter**，不走管理端 Bearer |

- 管理端由框架按包名加 `{admin-prefix}`；Controller **只写资源路径**
- 管理端 REST：`POST /create` · `PUT /update` · `DELETE /delete` · `GET /get` · `GET /page` · `GET /export-excel`
- 外部鉴权算法可不同（JWT / HMAC），**目录结构必须统一**

---

## 8. 分层（摘要）

| 层 | 做 | 禁止 |
|----|----|------|
| Controller | `@Valid`、权限、调 Service、`return success(data)` | 事务、Mapper、吞异常、手写 `{admin-prefix}` |
| VO | Create / Update / Page / Resp / Excel + BaseVO | 业务字段乱塞 BaseVO |
| Service | 规则、事务、编排、返回 RespVO | 返回 DO、`return CommonResult.error` |
| Convert | MapStruct 字段映射 | 业务 if |
| DAL | `BaseDO` + `BaseMapperX` + `xxxIfPresent` | 手写 null 拼条件 |

注入用 `@Resource`。Service：`@Slf4j` `@Service` `@Validated`。

---

## 9. 统一响应与错误码（强制）

```json
{ "code": 0, "data": {}, "msg": "" }
```

- 成功：`code === 0`；HTTP 多为 200，以 body 为准
- ErrorCode 定义在 `*-api`；Service **只** `throw exception(ERROR_CODE)` 或 `invalidParamException`
- 禁止 `RuntimeException` 表达业务错误；禁止 `exception0` / 私有 `authFailed(String)` 运行时拼 msg
- **一场景一常量**：缺参、格式错、不存在、时间窗......各自 msg；仅签名/token 不匹配允许笼统「签名验证失败」
- Filter / 全局异常透传 `ServiceException` 的 code + message，不得改回笼统文案

完整条文与模板见 [coding.md](coding.md) § 错误码、[reference.md](reference.md) § 错误码。

---

## 10. 配置与日志（摘要）

| 层级 | 职责 |
|------|------|
| 启动类 | 只 `@SpringBootApplication` + 扫描 `{base}.server` / `{base}.module` |
| 域内 `*Configuration` | `@EnableConfigurationProperties` + 本域 Bean |
| `*Properties` | 绑定 YAML，无业务逻辑 |

日志五层（应用 / 访问 DB / 错误 DB / 操作 DB / 集成审计）见 [reference.md](reference.md)。要点：

- Service 禁止空 catch；禁止 log 明文 password / secret / sign / token
- 访问日志 DB **默认只覆盖管理端前缀**；`/external/**` 必须有域内审计表
- 前缀：`[{domain}] {动作} key={}`

---

## 11. 推荐默认

| 项 | 默认 |
|----|------|
| 新表删除 | `@TableLogic`；历史业务删除字段触达再统一 |
| 跨模块调用 | 2+ 模块才抽 Api 接口 |
| 开放接口 | 每个 `/external/{系统}` 必有 Filter + 审计表 |
| 生产访问日志 | 管理端 enable |
| HTTP 失败 | 对内 200 + body.code；网关可映射 4xx |
| 旧代码 | 触达再改，不一次性重构 |

---

## 12. 反例

| ❌ | ✅ |
|----|-----|
| Controller → Mapper | Controller → Service → Mapper |
| 启动类堆 EnableConfigurationProperties | 域内 Configuration |
| external 复用 admin Token | 独立 Filter |
| 以为 external 会进访问日志 DB | 仅管理端前缀；外部走审计表 |
| 空 catch / log 打 secret | warn + 脱敏 |
| Controller 写 `{admin-prefix}/...` | 只写 `/{domain}/{resource}` |
| `exception0` / 私有 helper 拼 msg | api 定义 ErrorCode + `throw exception(...)` |
| 多种失败共用一句笼统 msg | 每场景独立 ErrorCode（安全敏感除外） |
| 业务类放进 framework | 业务进 `module-*` |

---

## 13. 交付前

走 [checklist.md](checklist.md) 对应清单（新工程 / 新模块 / 新接口 / 开放接口 / PR）。

规则文件模板（复制到目标仓库 `.cursor/rules/`）：[templates/java-backend-standards.mdc](templates/java-backend-standards.mdc)

2：你应该如何与AI对话

如何与AI进行需求沟通呢，我见过太多很多人和AI沟通到最后摔键盘，骂AI，等等自己无语，各种情况，今天我教你如何解决这类问题。

与AI沟通的时候，AI产出的结果与你的不匹配核心原因就是AI没有彻底理解到你的需求具体细节，所以结果与预期不一致，打个比方，你和一个外国人沟通，外国人会一些中文，在中国汉语大家都知道的一个词在不通常下会出现各种意思，比如人要是行，干一行，行一行，一行行，行行行，这外国人咋理解？你不说清楚他就阿巴阿巴了，反正读出来就是了。

和AI对话的本质也是一样，你的需求越模糊它的范围就越广，你必须要把它框在你所约束的范围之内，具体的需求明确告诉它，这样才是完美的，不要一上来就，我这个需求给我实现一下，你应该做的是，先讨论-> 再审查 -> 设计，->实现 -> 验证 -> 测试，这样的一个来回过程。

3: 与AI对话你应该掌握几种技巧

充分使用skill
不会的地方先出方案，再考虑，不要直接写代码
描述要尽可能清晰，而不是一带而过
写的过程中发现问题，让AI及时总结问题并沉淀到skill中
参考企业级的规范，而不是自己定义
参考社区好的项目
每个agent负责各自的事情，不要穿插需求，设计，代码，bug解决😎。

4：如何进行AI代码检测和测试验证

首先，你必须做到关键的接口你需要自查一遍，看看是否符合规范，bug等问题。
按照你的功能需求点制作冒烟测试条例，写自动测试脚本。
代码规范性校验，例如跑之前先执行eslint这种约束。
重要涉及到高风险的接口功能我更建议人工测试，仍需要保留。

5：如何下载skill

快速通道

哦，对对对，之前给女朋友求婚成功了，分享一下，马上就要结婚领证了，哈哈哈哈祝我好运，

6：分享结尾

好了，今天的分享就到这里，创作不易，花了很长的时间整理这个，也算是自己的一种能力提升吧，还是那句话，我是前端小张同学，期待你的关注，后续跟大家分享一下如何用AI进行测试💐💐💐。