AI编程⑫：用Cursor生成一个好对接的接口文档

视频主题&项目背景

  • 主题： 分享个人如何使用cursor 从0到1开发一个比较大的项目，使用的技术栈是vue+小程序+java
  • 项目

一个B2B的订货商城及供应链全流程管理，包含的端有：

  • 小程序商城端
  • 供应商端
  • 仓储物流端
  • 司机配送端
  • 销售端
  • 后台管理系统

以上小程序端都是使用webview的方式

核心功能：

  • 商城的基本功能: 正逆向订单、商品、购物车、优惠券、积分、钱包、充值、工单等
  • 供应链的基本功能：采购、仓储出入库，司机配送（仓库功能比较简单，只是一个中转仓功能）
  • 供应商基本功能：上品、财务核算、送货

目前项目大部分已完成，人数一人
个人技术栈：偏后端

使用工具： cursor主力+trae+augment(浅用）

整体流程

需求->原型页面->正式页面->后端开发->测试->上线

流程环节

Cursor开发量

人工开发量

说明

输出

需求

0%

100%

定制需求，大部分人工处理，其实需求更多是流程，老板是一个概念或者现有的流程，我们做的事情是线上化，效率化

基本上所有端（角色）的简要的需求功能

原型页面

100%

0%

全部AI生成，这部分是要给老板确认，目的是大方向不要错

原型界面

举例子：供应商小程序端

正式页面

100%

0%

生成正式界面和接口文档，这一步非常重要，如果做不好，可能后面前后端对接的时候将会是灾难性的

前端界面（可直接使用）

接口文档

后端开发

90%

10%

人工的部分只要是两种：
1、解决AI兜兜转转总是解决不了，因为AI很容易陷入一种自我满足的死循环中，一个简单的问题它可以处理的非常复杂，所以必须人工干预
2、手写一些通用性的功能，比如拦截器、日志类、权限验证、数据库初始化这些基本不变但又是非常重要的东西

人工建表80%

服务

 

测试

50%

50%

AI做单元测试，人工做联调测试

 

Curosr开发流程

原型部分

了解老板的核心需求，把核心需求列成功能点，通过功能点生成原型界面，目的是在最快的时间能出来一个东西，方便进行下一次沟通。

  • 先出全部页面，再局部调整

图片1(4)

配合UI提示词

你是一个专业的UI设计师，你需要根据我提供的需求文档来完成页面的设计

请仔细阅读 需求文档 @supplier.md， 现在需要输出高保真的原型图，请通过以下方式帮我完成所有界面的原型设计，并确保这些原型界面可以直接用于开发：

1、用户体验分析：先分析这个 App 的主要功能和用户需求，确定核心交互逻辑。

2、产品界面规划：作为产品经理，定义关键界面，确保信息架构合理。

3、高保真 UI 设计：作为 UI 设计师，设计贴近真实 iOS/Android 设计规范的界面，使用现代化的 UI 元素，使其具有良好的视觉体验。

4、HTML 原型实现：使用 HTML + Tailwind CSS（或 Bootstrap）生成所有原型界面，并使用 FontAwesome（或其他开源 UI 组件）让界面更加精美、接近真实的 App 设计。拆分代码文件，保持结构清晰：

5、每个界面应作为独立的 HTML 文件存放，例如 home.html、profile.html、settings.html 等。

• index.html 作为主入口，不直接写入所有界面的 HTML 代码，而是使用 iframe 的方式嵌入这些 HTML 片段，并将所有页面直接平铺展示在 index 页面中，而不是跳转链接。

• 真实感增强：  - 界面尺寸应模拟 iPhone 15 Pro，并让界面圆角化，使其更像真实的手机界面。

• 使用真实的 UI 图片，而非占位符图片（可从 Unsplash、Pexels、Apple 官方 UI 资源中选择）。

• 添加顶部状态栏（模拟 iOS 状态栏），并包含 App 导航栏（类似 iOS 底部 Tab Bar）。

请按照以上要求生成完整的 HTML 代码，并确保其可用于实际开发

图片1(5)

使用claude-4-sonnet thinking 模式，出的效果非常好，后面就是对整体页面进行局部调整

用这个版本生成各个端的原型页面，跟老板确认需求，为下一步正式页面开发做好准备

*前端部分

页面生成

生成前端界面目前普遍有三种办法

  • 使用第三方的设计工具进行代码转换，比如figma-ai
  • 使用截图的方式，丢给cursor让它模仿页面的中元素，结构，颜色等
  • 使用提示词的方式直接生成

我主要用后两种，因为已经生成了原型，可以直接剪切原型的图片，让cursor生成代码，原型主要是结构和元素

前端类型

生成界面方法

生成的顺序

提示词

小程序/app/h5

截图/文字直接生成

先初始化一个空的框架，比如vue

在一个页面一个页面生成

对于通用型的界面，AI很容易识别并理解，比如我说”做一个充值界面“，就这几个字就够了，现生成出来，再细调

帮我生成一个适配移动端的h5空的框架，使用的技术是vue3+vant, 你只需要生成空的框架就行，不需要有任何示例测试页面。

后台管理系统

 

文字直接生成

 

先初始化一个空的框架，比如element-ui

然后生成管理菜单

再生成每个界面

帮我生成一个基于element-ui的后台管理系统框架，使用的技术是vue3+element-ui, 你只需要生成空的框架就行，不需要有任何示例测试页面。

API接口文档，定义统一返回值格式

接口文档非常重要，接口文档越早弄越好，如果没有接口文档，后面的前后端联调将是灾难性的。

在生成页面的时候，就要同时生成接口文档，可以配置以下rules来帮助我们自动生成，可以设置成always

Python
## 📖 API文档规范

### 文档同步要求
**当生成或修改API接口时，以下内容变更必须同步更新API文档：**
- 入参结构变更
- 返回参数变更  
- URL地址变更
- 请求方式变更

### 文档格式标准

#### 基本信息
```markdown
## 接口名称

**接口名称：** 简短描述接口功能
**功能描述：** 详细描述接口的业务用途
**接口地址：** /api/endpoint
**请求方式：** GET/POST
```

#### 功能说明
```markdown
### 功能说明
详细描述接口的业务逻辑，可以使用流程图或时序图：

```mermaid
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: 请求数据
    Server-->>Client: 返回结果
```

#### 请求参数
```markdown
### 请求参数
```json
{
  "page": 1,
  "page_size": 10,
  "status": "active"
}
```

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|-------|------|-----|------|--------|
| page | int | 否 | 页码（默认1） | 2 |
| page_size | int | 否 | 每页数量（默认10） | 20 |
| status | string | 否 | 状态过滤 | active |
```

#### 响应参数
```markdown
### 响应参数
```json
{
  "error": 0,
  "body": {
    "user_id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "status": "active"
  },
  "message": "获取用户基本信息成功",
  "success": true
}
```

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|-------|------|-----|------|--------|
| error | int | 是 | 错误码 | 0 |
| body | object | 是 | 响应数据 | |
| body.user_id | int | 是 | 用户ID | 1 |
| body.username | string | 是 | 用户名 | admin |
| body.email | string | 是 | 邮箱 | admin@example.com |
| body.status | string | 是 | 用户状态 | active |
| message | string | 是 | 响应消息 | 获取用户基本信息成功 |
| success | bool | 是 | 是否成功 | true |
```

**注意：** 如果body是对象，需要列出所有子字段，格式为 `body.字段名`

参数说明和功能描述最重要，这是我们生成后端部分的重要文档

 

 

 

*Java后端部分

图片1(6)

  • 准备好两份rules：

   一个rules能描述你的java编码规范以及分层结构

   一个是做你代码方法的索引，让cursor在生成代码的时候优先去找存在的方法，提高复用性

 

  • 先用io 初始化一个空项目，手动分层建好，比如controller--> service-->mapper

生成Mapper

根据表结构生成mapper, mapper 一般是通用的，可以用下面的提示词生成

Markdown
请读取 tables.md sql语句，为每个表生成独立entity,mapper接口以及对应的xml文件，要求包含通用的增加、删除、修改、查询方法，详细如下：
- 单个增加
- 批量增加
- 根据id 更新
- 通用查询，以entity 为condition
- 根据id查询
- 根据ids查询
- 根据id删除（软删除）
- 根据ids 删除（软删除）

根据rules和这个提示词生成mapper 后，算是完成了底层的通用性构造

图片1(7)

根据接口文档生成controller层和Service层的实现

从前端到后端

这里一定要用任务细分的工具，不然经常会漏掉代码或者逻辑有问题，尽量一个模块（五六个接口以内）一次对话中完成。

任务细分的工具我推荐两个：

一个是之前我介绍的“一个神奇rules"

一个是MCP 工具 shrimp-task-manager

 

先用plan模式进行分析，然后在用执行模式对任何进行执行

从后端到前端

也可以让后端生成API文档，发到前端来生成界面

图片1(8)

图片1(9)

根据mermaid或者自己描述流程来生成任务的视线或者MQ的实现

  • 你可以使用流程图工具mermaid把整个任务处理的流程还画出来，然后转换成文字复制到cursor对话中

 

  • 你可以画流程图截图的方式放到对话上下文中
  • 用文字的方式来实现流程。我一般用这种方式，把流程描述出来。

首先、然后、其次。。。

 

 

问题

图片1(10)

图片1(11)

 

 

 

  • 补全 rules
  • 每次对话都要加上 需要注意的内容

图片1(12)

工具&Rules分享

 

  • MCP task-manager
  • Cursor 到 IDE 跳转

图片1(13)

IDE到cursor跳转

图片1(14)

posted @ 2025-09-12 15:20  周大福001  阅读(423)  评论(0)    收藏  举报