1. 为什么要在 Cursor 里生成 Java 架构设计图接手一个 Spring Boot 老项目时最头疼的不是改代码而是搞清楚模块之间到底怎么调用的。README 通常只写了怎么启动但 Controller 调了哪些 Service、Service 又依赖哪些 Mapper、数据从哪个外部接口进来、异常在哪里被兜底这些信息散落在几十个文件里。靠人肉翻代码画图一个中等规模的项目能耗掉大半天。Cursor 这类 AI 编辑器在这里能帮上大忙它可以直接读取整个工程目录理解包结构和类之间的引用关系然后按你给的提示词输出 Mermaid 语法的架构图。Mermaid 的好处是纯文本描述图形能直接嵌进 Markdown 文档配合预览插件就能在编辑器里看到渲染结果改起来也方便不用像 draw.io 那样拖拽半天。这套流程适合几类人刚接手陌生 Java 项目的开发者、需要给团队补架构文档的维护者、以及想把架构图产出接入统一 AI 工具链的团队。核心检索词就是 Cursor、Java、架构设计图、Mermaid、Markdown 这几个整篇围绕怎么在 Cursor 里把这几样串起来讲。不过实际用下来会发现一个问题Cursor 默认走的是它自己的模型通道团队里如果有多个人、多个项目Key 管理会很乱。所以我会在流程里顺带把 TaoToken 的统一 Key/API 通道接进来让 Cursor 的模型请求走一个可复用的入口这样架构图生成和日常编码用的是同一套配置换项目不用重新折腾。2. TaoToken 前置准备统一 Key 与 API 通道TaoToken 在这里扮演的角色是模型请求的统一入口。你可以把它理解成一个 API 网关Cursor 发出的模型调用请求通过配置指向 TaoToken 的 API 地址用同一个 Key 就能访问背后的模型能力。对团队来说好处是 Key 集中管理不用每个人各自去申请、各自配置项目之间切换也不用改一堆东西。需要提前准备的东西不多先去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台里创建一个 API Key。这个 Key 就是后面配置里要填的凭证。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 的基础地址是 https://taotoken.net/api 注意这个地址后面不加任何查询参数配置时直接填这个就行。如果你用的是 Cursor 的 Chat 功能做架构图生成模型选择上建议用长上下文、代码理解能力强的模型因为要一次性读进整个工程目录。具体模型名以控制台里可选的为准配置时填对应的模型标识。注意Key 属于敏感凭证不要直接提交到 Git 仓库。建议放在本地配置文件里或者用环境变量注入。3. 可复制配置settings.json 骨架与 Cursor 接入Cursor 的模型配置可以通过 settings.json 来管理。下面是一个配置骨架把 TaoToken 的 API 通道接进来。你需要把your-api-key-here替换成自己在控制台创建的真实 Key。{ cursor.general.enableAutoSave: true, cursor.chat.model: your-model-name, cursor.chat.apiBase: https://taotoken.net/api, cursor.chat.apiKey: your-api-key-here, cursor.chat.temperature: 0.3, cursor.chat.maxTokens: 8192, cursor.chat.customHeaders: { Content-Type: application/json }, files.associations: { *.md: markdown }, markdown.preview.breaks: true }几个参数说明一下。apiBase填 TaoToken 的 API 地址注意结尾不要带斜杠。apiKey填控制台生成的 Key。temperature设成 0.3 是因为架构图生成需要稳定输出太高的随机性会导致每次生成的图结构差异很大。maxTokens给大一点因为一个完整的架构文档包含多个图表输出内容会比较长。如果你不想把 Key 写死在 settings.json 里可以用环境变量。在系统环境变量里设置TAOTOKEN_API_KEY然后配置改成{ cursor.chat.apiKey: ${env:TAOTOKEN_API_KEY} }这样 Key 就不会出现在配置文件里团队协作时每个人本地设置自己的环境变量即可。配置改完后重启 Cursor让设置生效。然后打开你的 Java 工程目录确认 Cursor 能正常索引到项目文件。可以在 Chat 窗口里随便问一句「这个项目有哪些顶层包」看它能不能正确回答能回答说明模型通道已经通了。4. 生成 Mermaid 架构图的完整操作配置通了之后接下来就是实际的生成动作。核心思路是给 Cursor 一个结构化的提示词让它读取工程代码然后按指定的图表类型输出 Mermaid 语法。4.1 准备提示词文件在项目根目录建一个prompt-arch.md文件把下面这段提示词放进去。这个提示词定义了要生成的图表类型、样式规范和换行语法要求。# Mermaid 工程架构图生成提示 请为我的 Spring Boot 项目生成使用 Mermaid 语法的架构图以 Markdown 格式呈现。 ## 需求说明 1. 使用 Mermaid 语法创建多个图表展示不同架构视图 2. 所有图表嵌入一个 Markdown 文件标题为项目模块架构设计 3. 图表清晰展示组件关系和数据流 4. 节点填充色用浅色文字和边框用深色#000 或 #333 5. 节点文本换行使用 br不要用 \n ## 需要包含的图表类型 ### 1. 模块依赖图 使用 graph TD 语法展示主要模块依赖关系和内部组件结构 区分 Controller、Service、Mapper 等展示调用关系。 ### 2. 系统部署架构图 使用 flowchart TD 语法展示生产环境部署结构 包括客户端、负载均衡、应用服务器、数据库、外部系统。 ### 3. 数据流程图 使用 flowchart LR 语法展示数据从数据源到存储的完整流程。 ### 4. 核心业务流程图 使用 sequenceDiagram 语法展示主要业务流程的时序关系。 ### 5. 数据库 ER 图 使用 erDiagram 语法展示主要数据实体及关系。 ### 6. 接口调用关系图 使用 flowchart TB 语法展示内部组件间接口调用关系。 ### 7. 异常处理流程图 使用 flowchart TD 语法展示异常处理机制。 ### 8. 性能优化设计图 使用 flowchart LR 语法展示主要性能优化策略。 ## 格式要求 - 每个图表前有简短说明 - 使用 %% 添加注释 - 样式定义中添加 color:#000 属性 - 文档最后添加总结部分4.2 在 Chat 窗口触发生成按Ctrl L打开 Chat 窗口输入以下内容prompt-arch.md src 请根据提示词文件和工程代码生成完整的架构设计文档 输出为 Markdown 格式保存到 docs/architecture.md这里的prompt-arch.md是引用提示词文件src是引用源码目录。Cursor 会把这两个内容一起送给模型模型读取代码结构后按提示词要求生成图表。生成过程中你会看到它逐个输出图表。如果项目比较大可能需要等一两分钟。生成完成后在docs/architecture.md里就能看到完整的 Markdown 文档里面包含多个 Mermaid 代码块。4.3 预览与编辑要预览 Mermaid 渲染效果需要安装Markdown Preview Mermaid Support插件。在 Cursor 插件市场搜索安装然后打开architecture.md按CtrlShiftV打开预览就能看到渲染后的架构图。如果某个图不满意比如模块依赖图的布局太乱可以把对应的 Mermaid 代码块复制出来打开 draw.io依次点击「调整图形」→「插入」→「高级」→「Mermaid」粘贴代码后就能转成可拖拽编辑的图形改完再导出。5. 验证请求与成功结果配置和生成都做完后需要验证整条链路是通的。分两步先验证 TaoToken 通道再验证架构图产出。5.1 验证 API 通道连通性在终端里用 curl 发一个最简单的请求确认 Key 和地址配置正确curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer your-api-key-here \ -d { model: your-model-name, messages: [ {role: user, content: 回复 OK 两个字母即可} ], max_tokens: 10 }如果返回的 JSON 里有choices字段且内容包含OK说明通道正常。如果返回 401检查 Key 是否正确返回 404检查 API 地址是否写错。5.2 验证架构图生成结果回到 Cursor在 Chat 窗口里问一个具体问题来验证模型是否真的读懂了工程src 这个项目里 OrderController 调用了哪些 Service请列出调用链。如果它能准确说出OrderController→OrderService→OrderMapper这样的链路说明代码索引和模型理解都正常。然后再让它生成单个图表做快速验证src 只生成模块依赖图用 graph TD 语法输出 Mermaid 代码块。拿到输出后粘贴到 https://mermaid.live 或者本地预览插件里看是否能正常渲染。渲染成功且节点关系合理就说明整条链路打通了。成功的标志是docs/architecture.md文件存在包含 8 个左右的 Mermaid 代码块预览时每个图都能渲染出来节点文字清晰可读模块之间的依赖箭头方向正确。6. 本篇常见错误排查实际操作中容易踩几个坑这里集中说一下。图表渲染失败提示语法错误。最常见的原因是节点文本里用了\n换行。Mermaid 不认这个必须用br。比如A[第一行\n第二行]会报错要写成A[第一行br第二行]。另外节点文本里如果有括号、引号等特殊字符要用双引号把整个文本包起来比如A[包含(括号)的文本]。生成的图文字看不清。默认样式下节点填充色可能比较深文字也是深色叠在一起就糊了。解决办法是在提示词里明确要求classDef里加color:#000并且填充色用浅色系。如果已经生成了手动改一下classDef那几行就行。Cursor 读不到工程代码。检查是不是在 Chat 里忘了加src引用。另外如果项目太大索引可能没建完等右下角的索引进度条走完再试。还有一种情况是.cursorignore文件把某些目录排除了检查一下配置。API 请求返回 429。这是触发了速率限制。TaoToken 通道对请求频率有约束生成大文档时如果一次性请求太多可能会被限流。解决办法是拆成多次请求比如先让它生成模块依赖图和部署图再生成剩下的。或者在 settings.json 里把maxTokens调小一点减少单次请求的负载。生成的架构图和实际代码对不上。模型有时候会「合理推测」尤其是当代码里用了大量注解、AOP、动态代理时它可能看不到真实的调用关系。这种情况在提示词里加一句「如果信息不足请标注假设」然后人工核对关键链路。对于 Spring 的Autowired注入模型一般能识别但如果是ApplicationContext.getBean()这种动态获取就可能漏掉。draw.io 导入 Mermaid 后布局错乱。draw.io 对 Mermaid 的支持不是 100% 兼容复杂的sequenceDiagram和erDiagram导入后可能变形。建议只把flowchart和graph类型的图导入 draw.io 做微调时序图和 ER 图直接在 Markdown 里改代码更靠谱。7. 把架构图产出接入可复用工具链单次生成架构图不难难的是让团队里每个人都能稳定产出、格式统一。这里的关键是把配置和提示词都固化下来。配置层面把 settings.json 里的 TaoToken 通道配置抽成一个团队共享的模板新成员入职时直接复制只需要替换自己的 Key。Key 通过环境变量注入避免泄露。模型选择上统一用一个长上下文模型保证不同人生成的图表风格一致。提示词层面把prompt-arch.md提交到项目仓库的docs/目录下作为项目文档的一部分。这样任何人接手项目都能用同一套提示词重新生成或更新架构图。提示词里可以针对项目特点做定制比如你们项目用了 DDD 分层就在提示词里明确要求按application、domain、infrastructure分层来画。流程层面建议把架构图生成纳入项目文档维护的常规动作。每次有大的模块调整就重新跑一遍生成对比新旧图把变化点更新到文档里。Cursor 的 Chat 历史记录可以保留每次生成的上下文方便回溯。如果你日常编码和 Agent 任务比较多可以考虑用 Coding Plan 来统一管理模型调用额度地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。模型对话相关的入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关的配置参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。实际用下来这套流程最大的价值不是省了画图的时间而是让架构文档和代码保持同步变得可行。以前文档写完就过期现在改完代码顺手重新生成一遍几分钟的事。团队里新人的上手成本也低了很多不用再靠口口相传去理解模块关系。
