如何编写一个SpringBoot项目告警推送的Starter：TaoToken统一Key接入与配置骨架

1. 为什么要把告警推送做成一个 Starter线上服务最怕的不是报错而是报错了没人知道。接口偶发 500、某个请求耗时从 100ms 涨到 2s、JVM 堆内存持续爬升、慢 SQL 越来越多这些问题在彻底爆发前其实都有信号只是没人盯着看。如果每个业务项目都自己写一套「捕获异常 → 拼消息 → 调 webhook」的代码重复不说配置还散落在各处改一个阈值要翻好几个仓库。告警推送 Starter 要解决的就是这件事把异常捕获、慢请求统计、状态码监控、JVM 指标采集这些通用能力封装成一个自动装配的组件业务项目只要引入依赖、填一个 webhook 地址启动后就具备基础告警能力。它适合中小团队快速搭起告警链路也适合已有 Prometheus/Grafana 的团队补一个「实时推送」的入口。这篇会交付一套可复制的 Starter 骨架目录结构、spring.factories与 AutoConfiguration 写法、application.yml配置项以及用 TaoToken 统一 Key 接入告警通道的示例。最后给出本地启动验证告警发送的完整步骤照着做就能跑通。2. TaoToken 统一 Key 接入前置准备多工具告警通道最烦的是 Key 管理飞书一个 webhook、钉钉一个 access_token、企业微信一个 key散在配置文件里换环境就要改一遍。TaoToken 提供统一 Key 的方式把模型对话、编码 Agent、API 调用这些能力收敛到一个 Key 上告警通道的接入凭证也可以走同一套管理逻辑减少配置漂移。你需要先拿到一个可用的 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台在 API Keys 页面创建一个 Key。这个 Key 后面会写进 Starter 的配置里用于统一鉴权。创建 Key 的入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页面是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 这个不加 UTM。注意Key 只放在服务端配置或环境变量里不要提交到 Git也不要在前端代码里出现。建议用${TAOTOKEN_API_KEY}这种占位方式注入。如果你后面还要做长期编码或 Agent 相关的告警联动可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要直接对话验证模型是否通用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3. Starter 目录结构与自动装配骨架先看整体结构。Maven 多模块拆法核心逻辑和自动装配分开业务方按需引入alert-push-starter/ ├── alert-push-core/ # 核心模型与推送逻辑 │ └── src/main/java/com/example/alert/core/ │ ├── AlertMessage.java # 告警消息模型 │ ├── AlertPublisher.java # 推送接口 │ └── channel/ # 各通道实现 ├── alert-push-spring-boot-starter/ # 自动装配 │ └── src/main/ │ ├── java/com/example/alert/starter/ │ │ ├── AlertAutoConfiguration.java │ │ ├── AlertProperties.java │ │ └── AlertTemplate.java │ └── resources/META-INF/ │ └── spring.factories └── alert-push-demo/ # 本地验证示例AlertProperties负责绑定application.yml里的配置项用ConfigurationProperties声明package com.example.alert.starter; import org.springframework.boot.context.properties.ConfigurationProperties; ConfigurationProperties(prefix alert.push) public class AlertProperties { private boolean enabled true; private String webhook; private String webhookFormat feishu; private String serviceName unknown-service; private String environment dev; private String apiKey; private String apiBase https://taotoken.net/api; private Dedupe dedupe new Dedupe(); private ExceptionConfig exception new ExceptionConfig(); private RequestConfig request new RequestConfig(); // getter / setter 省略实际项目用 Lombok Data 即可 public static class Dedupe { private boolean enabled true; private int cooldownSeconds 300; // getter / setter } public static class ExceptionConfig { private boolean enabled true; private int stackTraceMaxLines 20; // getter / setter } public static class RequestConfig { private boolean enabled true; private long slowThresholdMs 1000; // getter / setter } }自动装配类把 Properties、Publisher、Template 串起来并用ConditionalOnProperty控制开关package com.example.alert.starter; import com.example.alert.core.AlertPublisher; import com.example.alert.core.channel.FeishuPublisher; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration EnableConfigurationProperties(AlertProperties.class) ConditionalOnProperty(prefix alert.push, name enabled, havingValue true, matchIfMissing true) public class AlertAutoConfiguration { Bean ConditionalOnMissingBean public AlertPublisher alertPublisher(AlertProperties props) { FeishuPublisher publisher new FeishuPublisher(); publisher.setWebhook(props.getWebhook()); publisher.setApiKey(props.getApiKey()); publisher.setApiBase(props.getApiBase()); return publisher; } Bean ConditionalOnMissingBean public AlertTemplate alertTemplate(AlertPublisher publisher, AlertProperties props) { return new AlertTemplate(publisher, props); } }spring.factories是自动装配的入口Spring Boot 2.x 用这个文件3.x 可以换成AutoConfiguration.importsorg.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.alert.starter.AlertAutoConfiguration如果是 Spring Boot 3.x在src/main/resources/META-INF/spring/下建org.springframework.boot.autoconfigure.AutoConfiguration.imports内容直接写类名com.example.alert.starter.AlertAutoConfigurationAlertTemplate是对外暴露的调用入口业务代码注入它就能手动发告警同时它内部也负责去重逻辑package com.example.alert.starter; import com.example.alert.core.AlertMessage; import com.example.alert.core.AlertPublisher; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; public class AlertTemplate { private final AlertPublisher publisher; private final AlertProperties props; private final MapString, Long lastSentAt new ConcurrentHashMap(); public AlertTemplate(AlertPublisher publisher, AlertProperties props) { this.publisher publisher; this.props props; } public void send(String title, String content) { String key title | content; if (props.getDedupe().isEnabled()) { long now System.currentTimeMillis(); Long last lastSentAt.get(key); if (last ! null now - last props.getDedupe().getCooldownSeconds() * 1000L) { return; } lastSentAt.put(key, now); } AlertMessage msg new AlertMessage(); msg.setServiceName(props.getServiceName()); msg.setEnvironment(props.getEnvironment()); msg.setTitle(title); msg.setContent(content); publisher.publish(msg); } }4. application.yml 配置项与 TaoToken Key 接入示例配置项按「总开关 → 通道 → 去重 → 异常 → 请求」的顺序组织最简配置只要三行alert: push: enabled: true webhook: https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx webhook-format: feishu完整配置带上 TaoToken 统一 Key 和各类阈值alert: push: enabled: true webhook: https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx webhook-format: feishu service-name: ${spring.application.name} environment: ${spring.profiles.active:dev} api-key: ${TAOTOKEN_API_KEY} api-base: https://taotoken.net/api dedupe: enabled: true cooldown-seconds: 300 exception: enabled: true stack-trace-max-lines: 20 request: enabled: true slow-threshold-ms: 1000几个关键参数对照配置项作用建议值enabled总开关truewebhook-format通道类型feishu / dingtalk / wecomapi-keyTaoToken 统一 Key环境变量注入dedupe.cooldown-seconds同类告警冷却窗口300request.slow-threshold-ms慢请求阈值1000exception.stack-trace-max-lines堆栈截断行数20api-key走环境变量注入本地启动时这样设置export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key提示api-base固定为https://taotoken.net/api不要带 UTM 参数那是给网页链接用的API 调用不需要。5. 本地启动验证告警发送验证分三步起服务、触发告警、看结果。第一步在 demo 模块里写一个测试 Controller模拟异常和慢请求package com.example.alert.demo; import com.example.alert.starter.AlertTemplate; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/demo) public class DemoController { private final AlertTemplate alertTemplate; public DemoController(AlertTemplate alertTemplate) { this.alertTemplate alertTemplate; } GetMapping(/ok) public String ok() { return ok; } GetMapping(/error) public String error() { throw new NullPointerException(demo 空指针告警); } GetMapping(/slow) public String slow(long millis) throws InterruptedException { Thread.sleep(millis); return slow millis; } GetMapping(/manual) public String manual() { alertTemplate.send(手动告警, 这是一条通过 AlertTemplate 发出的测试消息); return sent; } }第二步启动 demo 服务默认端口 18089cd alert-push-demo mvn spring-boot:run看到日志里出现AlertAutoConfiguration装配成功的记录说明 Starter 生效了。第三步触发告警并观察curl http://localhost:18089/demo/error curl http://localhost:18089/demo/slow?millis1500 curl http://localhost:18089/demo/manual/demo/error会触发异常告警/demo/slow?millis1500因为超过 1000ms 阈值触发慢请求告警/demo/manual走AlertTemplate手动发送。控制台会打印推送日志飞书群里能看到对应消息。如果只想验证 Key 是否可用不依赖 webhook可以先用模型对话页面发一条测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认 Key 鉴权通过后再接告警通道。6. 本篇常见错误排查自动装配没生效AlertTemplate注入失败。先检查spring.factories路径是否为src/main/resources/META-INF/spring.factoriesSpring Boot 3.x 则要确认用的是AutoConfiguration.imports。再看alert.push.enabled是否被设成了 falseConditionalOnProperty的matchIfMissing true只在配置项缺失时生效。配置项绑定不上webhook为 null。ConfigurationProperties(prefix alert.push)的前缀要和 yml 里的层级完全对应yml 缩进用空格不用 Tab。如果用了EnableConfigurationProperties但没在自动装配类上加Properties 不会被注册。告警发出去了但群里没消息。先确认 webhook 地址完整飞书机器人地址以/open-apis/bot/v2/hook/开头。再看webhook-format和实际通道是否匹配格式填错会导致消息体结构不对接口返回 400。用 curl 直接打一次 webhook 地址排除网络和机器人配置问题。同类告警只收到一条。这是去重生效了cooldown-seconds默认 300 秒。调试阶段可以临时设成 0 或关掉dedupe.enabled上线前再打开。Key 鉴权失败返回 401。检查api-key是否通过环境变量正确注入echo $TAOTOKEN_API_KEY确认非空。Key 前后不要带空格或引号。如果 Key 泄露过去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个。慢请求告警不触发。确认request.enabled为 trueslow-threshold-ms小于实际请求耗时。如果请求路径在exclude-paths里会被跳过检查有没有把测试路径误加进去。接入相关的完整说明在文档页https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到装配或鉴权问题优先对照文档排查。7. 下一步把告警链路接到 Coding PlanStarter 跑通后告警入口就打通了。接下来可以做的扩展方向把告警消息和日志查询、指标采集串起来收到异常后自动拉取上下文再回推分析结果。这类联动如果涉及编码 Agent 或长期运行的自动化任务用 Coding Plan 会更顺https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要管理多个服务的 Key 和配额去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。新建 Key 在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。我实测下来Starter 这类组件的价值不在代码多复杂而在于「接入成本足够低」。业务方引入依赖、填一个 webhook、启动就能收到第一条告警这个体验比写一堆文档管用。先把异常和慢请求这两个最高频的场景跑通后面再按需加 SQL 监控、JVM 指标、状态码告警链路自然就长出来了。