1. Spring AI 提示词工程为什么总是散落一地如果你正在做 Spring AI 项目大概率遇到过这种局面聊天接口能跑通图像模型也能返回 URL但提示词全散落在各个 Controller 的字符串常量里。今天调一版系统提示词明天换个人接手又改回去团队里没有一份能复用的骨架。更麻烦的是用 Cursor 生成代码时AI 写出来的风格每次都不一样有人用构造器注入有人用字段注入有人把业务逻辑塞进 Controller。我试过把提示词直接写死在RequestMapping方法里短期看没问题一旦要支持多语言、多模型切换维护成本立刻爆炸。所以这篇要解决的核心问题是把 CO-STAR 框架作为系统提示词的组织方式把 Cursor Rules 作为代码生成风格的约束层再通过统一的 Key/API 通道配置让 Spring AI 项目里的提示词从零散技巧变成团队可复用的模板。CO-STAR 本身不复杂它是对提示词要素的一次逻辑重组Context 背景、Objective 目标、Style 风格、Tone 语气、Audience 受众、Response 响应格式。它像一张检查清单引导你一步步构建完整指令。适合谁适合已经在写 Spring AI 接口、但提示词管理混乱的开发者也适合想把 Cursor 纳入团队规范的技术负责人。下面我会按可跟做的顺序展开先讲清楚 CO-STAR 在 Spring AI 里怎么落成配置再给出 Cursor Rules 的写法然后是 settings.json 与 config.toml 的统一 Key 配置骨架最后用一次对话验证提示词生效并顺带跑通图像模型调用返回。2. TaoToken 前置统一 Key 与 API 通道在写提示词之前先把通道问题解决掉。Spring AI 默认走 OpenAI 协议你需要在配置里指定base-url和api-key。如果每个开发者本地各配一套测试环境和生产环境又不一样提示词还没复用配置先乱了。TaoToken 在这里的作用是提供统一的 API 通道官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你可以在控制台创建 Key然后让 Spring AI 的base-url指向这个通道api-key用同一个 Key。这样团队里所有人拉同一份配置骨架只需要替换 Key 的值不用改代码。具体操作路径进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key地址在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后先别急着写进代码我们把它放到环境变量或配置文件里后面会给出 settings.json 和 config.toml 两种骨架。注意Key 不要提交到 Git 仓库用环境变量注入或者本地配置文件加.gitignore的方式管理。这一步做完你就有了一条稳定的通道接下来所有提示词实验都走这条通道换模型、换参数都不用动业务代码。3. 可复制配置CO-STAR 系统提示词骨架3.1 用 CO-STAR 组织系统提示词CO-STAR 的六个要素在 Spring AI 里可以映射成一份结构化的系统提示词模板。我把它写成一段可以直接放进application.yml或者独立资源文件的文本# Context背景 你是一个运行在 Spring AI 项目中的代码助手当前项目使用 Java 17、Spring Boot 3.5.3、Spring AI 1.0.1。 # Objective目标 根据用户输入的需求生成符合项目规范的 Java 代码片段并解释关键设计决策。 # Style风格 代码风格遵循阿里巴巴 Java 开发手册使用构造器注入禁止字段注入Controller 只做参数校验和转发。 # Tone语气 专业、简洁不寒暄直接给出结论和代码。 # Audience受众 阅读者是熟悉 Spring 生态的中级 Java 开发者不需要解释 Spring 基础概念。 # Response响应格式 先输出一段不超过三行的设计说明再输出完整代码块代码块标注语言为 java最后列出可能踩坑的点。这份模板的好处是每个要素独立成段团队 review 时能一眼看出哪一段被改了。你可以把它存成src/main/resources/prompts/system-co-star.txt然后在 Spring AI 里通过SystemPromptTemplate加载。3.2 Cursor Rules 约束代码生成风格Cursor Rules 是一组预先定义、可复用的系统级提示规则用来指导 AI 生成或修改代码时遵循特定规范。它和 CO-STAR 的分工是CO-STAR 管运行时提示词Cursor Rules 管开发时生成代码的风格。在项目根目录创建.cursor/rules/spring-ai-style.mdc内容如下--- description: Spring AI 项目代码生成规范 globs: [**/*.java] alwaysApply: true --- - 使用构造器注入禁止 Autowired 字段注入 - Controller 方法只做参数校验和 service 调用业务逻辑放 Service 层 - 所有提示词常量抽取到 prompts 包下的类或资源文件禁止硬编码在方法体内 - 图像模型调用统一封装成 ImageService返回 URL 而不是直接打印 - 异常统一用自定义 BusinessException禁止吞异常这样你在 Cursor 里让 AI 生成代码时它会自动带上这些约束。实测下来团队里新人的代码风格差异会明显缩小。3.3 settings.json 与 config.toml 配置骨架不同工具链的配置文件格式不一样这里给出两份骨架。第一份是 Cursor 的settings.json放在.cursor/settings.json{ springAi.project: { javaVersion: 17, springBootVersion: 3.5.3, springAiVersion: 1.0.1 }, taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultChatModel: gpt-4o-mini, defaultImageModel: qwen-image }, prompt: { systemTemplatePath: src/main/resources/prompts/system-co-star.txt, enableFewShot: true, enableCoT: true } }第二份是config.toml适合放在项目根目录供脚本读取[spring.ai.openai] base-url https://taotoken.net/api api-key ${TAOTOKEN_API_KEY} chat.options.model gpt-4o-mini chat.options.completions-path /v2/chat/completions image.options.model qwen-image image.options.images-path /v2/images/generations [prompt.co-star] context Spring AI 项目代码助手 objective 生成符合规范的 Java 代码 style 阿里巴巴 Java 开发手册 tone 专业简洁 audience 中级 Java 开发者 response 设计说明 代码块 踩坑点这两份配置的核心是把 Key 和通道抽出来提示词模板路径也抽出来业务代码只依赖接口不依赖具体值。3.4 Spring AI 里加载 CO-STAR 模板在 Spring AI 中你可以用SystemPromptTemplate把上面的文本模板加载进来Configuration public class PromptConfig { Bean public SystemPromptTemplate systemPromptTemplate( Value(classpath:prompts/system-co-star.txt) Resource resource) throws IOException { String template new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8); return new SystemPromptTemplate(template); } }然后在 Service 里组合用户输入Service public class ChatService { private final ChatClient chatClient; private final SystemPromptTemplate systemPromptTemplate; public ChatService(ChatClient.Builder builder, SystemPromptTemplate systemPromptTemplate) { this.chatClient builder.build(); this.systemPromptTemplate systemPromptTemplate; } public String chat(String userMessage) { PromptTemplate promptTemplate new PromptTemplate({input}); promptTemplate.add(input, userMessage); return chatClient.prompt() .system(systemPromptTemplate.render()) .user(promptTemplate.render()) .call() .content(); } }这段代码的关键点是系统提示词从资源文件加载用户输入单独渲染两者不混在一起。这样你改提示词不用重新编译 Java 代码。4. 验证请求一次对话确认提示词生效配置写完了得验证。先启动 Spring Boot 应用确认base-url指向 TaoToken 通道api-key从环境变量读取。export TAOTOKEN_API_KEY你的Key mvn spring-boot:run然后发一个请求curl -X POST http://localhost:8080/chat \ -H Content-Type: application/json \ -d {message:写一个 Spring AI 调用图像模型的 Service 方法}如果提示词生效返回内容应该符合 CO-STAR 里定义的 Response 格式先三行设计说明再代码块最后踩坑点。如果返回的是一大段寒暄说明系统提示词没加载进去检查systemPromptTemplate.render()是否被调用。接着验证图像模型调用。在 Controller 里加一个接口RestController RequestMapping(/image) public class ImageController { private final ImageModel imageModel; public ImageController(ImageModel imageModel) { this.imageModel imageModel; } GetMapping(/generate) public String generate(RequestParam String prompt) { ImageResponse response imageModel.call( new ImagePrompt(prompt, OpenAiImageOptions.builder() .quality(hd) .N(1) .height(1024) .width(1024) .build())); return response.getResult().getOutput().getUrl(); } }请求curl http://localhost:8080/image/generate?prompt一只在键盘上敲代码的猫成功的话会返回一个图片 URL。这里注意images-path要配成/v2/images/generations模型名用qwen-image或你通道支持的图像模型。如果返回 404先检查base-url和images-path拼接后的完整地址是否正确。提示验证阶段建议把日志级别调到 DEBUGSpring AI 会打印实际请求的 URL 和 payload方便定位是配置问题还是提示词问题。5. 本篇常见错排查第一个坑base-url结尾多了斜杠。Spring AI 拼接completions-path时如果base-url是https://taotoken.net/api/拼出来会变成双斜杠部分网关会返回 404。统一写成不带结尾斜杠的形式。第二个坑系统提示词没生效。常见原因是用了chatClient.prompt().user(...)但忘了.system(...)或者SystemPromptTemplate的占位符没替换。检查模板里是否有{input}这类未填充的变量。第三个坑Cursor Rules 不生效。.cursor/rules目录名和.mdc后缀要写对alwaysApply: true才会对所有文件生效。如果只想对 Java 文件生效用globs限定。第四个坑图像模型返回空 URL。先确认通道支持该图像模型再检查N、height、width参数是否在模型支持范围内。有些模型不支持quality参数传了会被忽略或报错。第五个坑Key 泄漏。如果你把 Key 写进了application.yml并提交了立刻去控制台吊销重建。正确做法是用${TAOTOKEN_API_KEY}占位本地用环境变量或.env文件。第六个坑CO-STAR 模板太长导致 token 超限。系统提示词不是越长越好把稳定不变的部分放模板动态部分放用户输入。如果模板超过 2000 token考虑精简 Audience 和 Tone 段落。6. 把模板沉淀成团队资产走到这里你已经有了三样东西一份 CO-STAR 系统提示词模板、一份 Cursor Rules 约束文件、一份统一的 Key/API 通道配置骨架。接下来要做的不是继续加功能而是把这三样东西放进团队仓库的docs/prompt-engineering/目录配一份 README 说明每个文件的用途和修改流程。如果你在排障或接入阶段遇到通道问题可以直接看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对 Spring AI 的配置示例。想先验证模型对话是否通用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速试一条。如果团队要长期做编码和 Agent 开发Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更适合把额度集中管理。最后留一个实用技巧每次改完 CO-STAR 模板用同一组测试用例跑一遍回归把输入和期望输出存成prompt-regression.json。这样提示词改动不再是玄学而是可验证的工程行为。
