HermesAgent集成Sentinel需五步：确认兼容性、注解定义资源、编程式SphU.entry接入、对接Dashboard动态管理、配置BlockExceptionHandler统一限流响应。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
一、确认HermesAgent与Sentinel的兼容性配置
在集成Sentinel前，需确保HermesAgent所处的运行环境满足Sentinel核心库的依赖要求。Sentinel核心包仅依赖Java 8+运行时，不强制绑定特定通信协议或代理框架，但需明确HermesAgent是否基于Spring Boot、Dubbo或自定义HTTP网关实现。若HermesAgent以独立Java进程暴露gRPC/HTTP服务，则可直接引入Sentinel适配器进行资源标记与规则注入。
1、检查HermesAgent项目中是否存在spring-boot-starter-web或dubbo-spring-cloud-starter等主流框架依赖。
2、确认JVM启动参数未禁用Java Agent机制（如未设置-XX:+DisableAttachMechanism），因部分Sentinel动态规则推送依赖Attach API。
3、验证当前HermesAgent版本是否已内置Metrics上报通道，以便Sentinel Dashboard能采集实时QPS与RT数据。
二、通过注解方式为HermesAgent接口定义Sentinel资源
使用@SentinelResource注解是最轻量级的资源定义方式，适用于HermesAgent中已明确暴露的业务方法。该方式无需修改调用链路，仅需在目标方法上声明资源名与降级逻辑，由Sentinel AOP切面自动织入流量控制逻辑。
1、在HermesAgent的服务类中，为待保护的方法添加@SentinelResource注解，并指定唯一资源名，例如：@SentinelResource(value = "hermes.agent.route.invoke", blockHandler = "handleBlock")。
2、在同一类中定义handleBlock方法，该方法签名须与原方法一致，并额外接收BlockException参数，用于返回兜底响应。
3、确保该类被Spring容器管理（如标注@Service或@Component），且项目中已启用@EnableAspectJAutoProxy或默认AOP支持。
三、通过SphU.entry编程式接入资源保护
当HermesAgent采用非Spring托管的线程模型（如Netty EventLoop直连处理）时，注解方式不可用，必须使用SphU.entry()手动构造资源入口。该方式提供最大控制粒度，适用于高性能场景下的细粒度限流。
1、在HermesAgent请求处理逻辑起始位置插入try(Entry entry = SphU.entry("hermes.agent.upstream.timeout")) { ... }语句块。
2、将原始业务逻辑置于try块内，确保所有可能抛出异常的路径均被覆盖。
3、在catch(BlockException ex)分支中构造统一降级响应，例如返回预设的JSON错误体并设置HTTP状态码为429。
4、确保每次entry()调用后均有对应exit()释放，若使用try-with-resources则自动保障。
四、对接Sentinel Dashboard实现动态规则管理
Dashboard作为Sentinel的可视化管控中心，支持对HermesAgent实例实时下发限流、熔断、系统保护等规则。需在HermesAgent启动时主动注册至Dashboard，并开放Transport端点供其拉取指标。
1、在HermesAgent的application.yml中添加Sentinel Transport配置：spring.cloud.sentinel.transport.dashboard: 172.50.2.40:8718。
2、确保HermesAgent所在主机防火墙放行8719端口（默认Heartbeat上报端口），否则Dashboard无法识别该机器在线状态。
3、启动HermesAgent后，访问Dashboard首页，在“簇点链路”页签中确认hermes.agent.route.invoke等资源已自动注册并显示实时调用数据。
4、在“流控规则”页签中，点击“+新增流控规则”，为目标资源设置QPS阈值、流控模式（直接/关联/链路）、流控效果（快速失败/排队等待）等参数。
五、配置自定义BlockExceptionHandler统一拦截限流响应
默认情况下，Sentinel抛出BlockException会中断正常流程并打印堆栈，不利于HermesAgent对外提供标准化错误格式。通过实现BlockExceptionHandler接口，可将所有限流/熔断异常转换为结构化HTTP响应或gRPC状态码。
1、新建类实现BlockExceptionHandler接口，重写handle方法，从中提取request、response及exception对象。
2、根据exception.getClass()判断具体异常类型（如FlowException、DegradeException），分别设置对应的状态码与错误信息。
3、调用response.getWriter().write(...)输出JSON格式错误体，例如：{"code":429,"message":"Request blocked by Sentinel flow control"}。
4、在Spring Boot启动类中，通过@PostConstruct或InitFunc注册该处理器实例至WebCallbackManager.setBlockHandler(...)。
