springbootAI 2.1.0__tar.gz → 2.2.0__tar.gz

{springbootai-2.1.0 → springbootai-2.2.0}/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 本项目从 `2.1.0` 开始按 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 记录面向使用者的变化，并使用语义化版本号。
 
+## [2.2.0] - 2026-08-12
+
+### 新增
+
+- 新增声明式 AOP：`@Aspect`、`@Pointcut`、`@Before`、`@After`、`@Around`、`@AfterReturning`、`@AfterThrowing`。支持受管 Bean 自动代理、同步/异步通知、`JoinPoint` / `ProceedingJoinPoint`，以及 `execution`、`within`、`bean`、`@annotation` 和切点引用。
+- 新增 `@PostAuthorize`，方法成功返回后可使用 `returnObject` / `#returnObject`、当前认证信息、角色和权限进行授权。
+- 新增 `@Recover`，在 `@Retryable` 重试耗尽后按异常类型选择最具体的恢复方法；兼容原有 `recover="method"` 写法和独立重试装饰器入口。
+- 新增面向新手的 [`AOP_SECURITY_RETRY.md`](doc/AOP_SECURITY_RETRY.md)，包含完整示例、执行顺序、表达式速查、安全边界和常见错误。
+
+### 安全与兼容性
+
+- 安全表达式改为白名单 AST 求值，不执行任意 Python 代码；不支持的语法按授权失败处理。
+- 声明式切面作为受管 Bean 的最外层扩展，可观察内置 AOP、重试和安全包装后的最终结果；手工实例化对象不会自动代理。
+- 旧式命名恢复方法继续保持原签名；显式命名的方法同时标记 `@Recover` 时使用包含最终异常的新签名。
+
+### 测试
+
+- 新增 26 个声明式 AOP、后置鉴权和重试恢复专项用例，并将 9 个新公共注解加入 172 项注解契约检查。
+- Conda Python 3.10.20 完整回归：2372 passed、4 skipped、172 subtests passed，覆盖率 68.63%。
+- Docker 真实集成测试：MySQL、Redis、RabbitMQ、Nacos、Seata TCC 共 5 项通过；Redis 和 Seata bridge 停机失败关闭 2 项通过。
+
+## [2.1.1] - 2026-08-12
+
+### 修复
+
+- 锁定兼容的 `langchain-core==1.5.4` 与 `langchain-openai==1.4.2`，避免可选 AI 依赖解析冲突。
+- CI 中间件恢复命令改用 `docker compose up -d --wait <service>`，兼容不支持 `start --wait` 的 Compose 版本。
+
 ## [2.1.0] - 2026-08-12
 
 ### 新增
@@ -34,4 +62,6 @@
 - Seata `distributed` 提供真实 TC + TCC 协调，不是 Python AT 数据源代理，不会自动生成 `undo_log`。
 - 内存 LangGraph checkpointer 仅用于测试；多 worker 生产环境必须注入共享存储后端。
 
+[2.2.0]: https://github.com/YUCONGGEN/springbootAI/compare/v2.1.1...v2.2.0
+[2.1.1]: https://github.com/YUCONGGEN/springbootAI/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/YUCONGGEN/springbootAI/compare/v2.0.2...v2.1.0

{springbootai-2.1.0/springbootAI.egg-info → springbootai-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.1.0
+Version: 2.2.0
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -56,16 +56,16 @@ Requires-Dist: sqlglot==27.28.1; extra == "ast"
 Provides-Extra: excel
 Requires-Dist: openpyxl==3.1.5; extra == "excel"
 Provides-Extra: ai
-Requires-Dist: langchain-openai==1.4.1; extra == "ai"
-Requires-Dist: langchain-core==1.5.1; extra == "ai"
+Requires-Dist: langchain-openai==1.4.2; extra == "ai"
+Requires-Dist: langchain-core==1.5.4; extra == "ai"
 Requires-Dist: langchain-classic==1.0.8; extra == "ai"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "ai"
 Requires-Dist: langchain-community==0.4.2; extra == "ai"
 Requires-Dist: numpy==2.2.6; extra == "ai"
 Requires-Dist: pydantic==2.13.4; extra == "ai"
 Provides-Extra: langchain
-Requires-Dist: langchain-openai==1.4.1; extra == "langchain"
-Requires-Dist: langchain-core==1.5.1; extra == "langchain"
+Requires-Dist: langchain-openai==1.4.2; extra == "langchain"
+Requires-Dist: langchain-core==1.5.4; extra == "langchain"
 Requires-Dist: langchain-classic==1.0.8; extra == "langchain"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "langchain"
 Requires-Dist: langchain-community==0.4.2; extra == "langchain"
@@ -108,8 +108,8 @@ Requires-Dist: defusedxml==0.7.1; extra == "full"
 Requires-Dist: requests==2.34.2; extra == "full"
 Requires-Dist: httpx==0.28.1; extra == "full"
 Requires-Dist: openpyxl==3.1.5; extra == "full"
-Requires-Dist: langchain-openai==1.4.1; extra == "full"
-Requires-Dist: langchain-core==1.5.1; extra == "full"
+Requires-Dist: langchain-openai==1.4.2; extra == "full"
+Requires-Dist: langchain-core==1.5.4; extra == "full"
 Requires-Dist: langchain-classic==1.0.8; extra == "full"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "full"
 Requires-Dist: langchain-community==0.4.2; extra == "full"
@@ -151,7 +151,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.1.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 当前验证的是官方 TC + TCC 回调，不会为 Python 数据库操作自动生成 AT `undo_log`。
+当前版本是 `2.2.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 当前验证的是官方 TC + TCC 回调，不会为 Python 数据库操作自动生成 AT `undo_log`。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -246,6 +246,7 @@ curl http://127.0.0.1:8080/api/hello/Alice
 |------|------|----------|-----------|
 | ✅ 新手入门 | [BEGINNER_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger |
 | ✅ 常用注解模块 | [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
+| ✅ AOP / 后置鉴权 / 重试恢复 | [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md) | 随核心包 | `@Aspect` 通知 / `@PostAuthorize` / `@Recover`，含小白示例与常见错误 |
 | 📦 AI（对接大模型） | [AI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / 多厂商适配 |
 | 📦 LangChain | [LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md) | `pip install springbootAI[langchain]` | Chains / Agents / Memory / Retrievers / VectorStores / 30+ 提供商 |
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
@@ -314,10 +315,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 2.1.0 |
-| `spring.orm.pymybatis` | 2.1.0 |
-| `spring.ai` AI 模块 | 2.1.0 |
-| `spring.langchain` LangChain 模块 | 2.1.0 |
+| `spring` 框架 API | 2.2.0 |
+| `spring.orm.pymybatis` | 2.2.0 |
+| `spring.ai` AI 模块 | 2.2.0 |
+| `spring.langchain` LangChain 模块 | 2.2.0 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -361,7 +362,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | 应用事件 | ✅ 可用 | `ApplicationEvent`、`@EventListener`、同步有序发布和异步监听 |
 | 内嵌 ORM + DDL Auto | ✅ 可用 | PyMyBatis + JPA ddl-auto 自动建表(create/update/validate)，支持 XML/注解 SQL、事务、缓存 |
 | 本地事务 | ✅ 可用 | `@Transactional` 支持七种 Spring 传播模式 |
-| JWT 与方法安全 | ✅ 可用 | access/refresh token、`@Authenticate`、角色/权限授权、401/403 映射 |
+| JWT 与方法安全 | ✅ 可用 | access/refresh token、`@Authenticate`、前置/后置授权、401/403 映射 |
 | 重试/异步 | ✅ 可用 | 受管 Bean 的退避重试、恢复方法和 Future/Task 异步调度 |
 | Redis/缓存 | ✅ 可用 | 分布式锁、KV/Hash/List/Set/Counter，需要 Redis 服务 |
 | RabbitMQ | ✅ 可用 | `@RabbitListener` 自动注册并后台消费，`RabbitTemplate` 发送 |
@@ -372,7 +373,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | API Gateway | ✅ 可用 | 轻量 ASGI/WSGI 网关，路由转发、路径重写、过滤器链、负载均衡 |
 | Prometheus 监控 | ✅ 可用 | Counter/Gauge/Histogram 指标暴露 |
 | Feign 声明式 HTTP | ✅ 可用 | 声明式接口、Fallback 降级、自动传播 XID 和 trace 头 |
-| 高级 AOP | ✅ 可用 | 限流、熔断、幂等、审计、锁、指标、追踪、缓存 |
+| 高级 AOP | ✅ 可用 | 声明式切面、限流、熔断、幂等、审计、锁、指标、追踪、缓存 |
 | AI 模块 | ✅ 可用 | ChatClient/ChatModel/EmbeddingModel/Advisor/Tools，OpenAI/Ollama/DeepSeek/Moonshot 适配 |
 | LangChain 模块 | ✅ 可用 | Chains/Agents(6 种)/Memory/Retrievers/VectorStores + 30+ 提供商，双向适配器 |
 | LangGraph 模块 | ✅ 可选 | 官方 LangGraph 状态图、条件路由、人工中断、持久化 checkpointer 和注解工作流 |
@@ -1005,7 +1006,7 @@ class ScheduledTasks:
         print("Current time:", time.time())
 ```
 
-**边界要点**：`max_retries=3` 包含首次调用；`@Async` 同步方法返回 `Future`；`@Scheduled` 多 worker 会重复执行。
+**边界要点**：`max_retries=3` 包含首次调用；重试耗尽可用 `@Recover` 按异常类型兜底；`@Async` 同步方法返回 `Future`；`@Scheduled` 多 worker 会重复执行。声明式切面、后置鉴权和恢复方法的完整小白示例见 [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md)。
 
 ### 5.10 安全、Cloud 与消息注解
 
@@ -1013,6 +1014,7 @@ class ScheduledTasks:
 |------|----------|--------------|
 | `@Authenticate` | 校验 JWT 并建立安全上下文 | 受管 Bean 实际执行；HTTP 控制器自动读取 `Authorization: Bearer ...` |
 | `@PreAuthorize` | 按角色/权限表达式授权 | 受管 Bean 实际执行；未认证返回 401，权限不足返回 403 |
+| `@PostAuthorize` | 根据方法返回值授权 | 受管 Bean 返回后执行；支持 `returnObject` / `#returnObject` |
 | `@Secured` | 按任一角色授权 | 受管 Bean 实际执行 |
 | `@SentinelResource` | 限流、业务异常 fallback | 受管 Bean 方法会包装；已内嵌限流熔断引擎 |
 | `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法调用 Seata manager |
@@ -1365,6 +1367,22 @@ def call_remote(self):
 
 **只对幂等操作开启自动重试**（如读操作）。写操作必须先设计幂等键。
 
+重试耗尽后可以使用 `@Recover`：
+
+```python
+from spring.annotations import Recover, Retryable
+
+@Retryable(value=(ConnectionError,), max_attempts=3, backoff=200)
+def call_remote(self, key):
+    raise ConnectionError("offline")
+
+@Recover(ConnectionError)
+def recover_remote(self, error, key):
+    return {"key": key, "status": "degraded", "reason": str(error)}
+```
+
+恢复方法选择、异步用法和常见错误见 [AOP / 后置鉴权 / 重试恢复指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md)。
+
 ### 11.3 @Async & @Scheduled
 
 ```python

{springbootai-2.1.0 → springbootai-2.2.0}/README.md

@@ -17,7 +17,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.1.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 当前验证的是官方 TC + TCC 回调，不会为 Python 数据库操作自动生成 AT `undo_log`。
+当前版本是 `2.2.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 当前验证的是官方 TC + TCC 回调，不会为 Python 数据库操作自动生成 AT `undo_log`。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -112,6 +112,7 @@ curl http://127.0.0.1:8080/api/hello/Alice
 |------|------|----------|-----------|
 | ✅ 新手入门 | [BEGINNER_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger |
 | ✅ 常用注解模块 | [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
+| ✅ AOP / 后置鉴权 / 重试恢复 | [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md) | 随核心包 | `@Aspect` 通知 / `@PostAuthorize` / `@Recover`，含小白示例与常见错误 |
 | 📦 AI（对接大模型） | [AI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / 多厂商适配 |
 | 📦 LangChain | [LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md) | `pip install springbootAI[langchain]` | Chains / Agents / Memory / Retrievers / VectorStores / 30+ 提供商 |
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
@@ -180,10 +181,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 2.1.0 |
-| `spring.orm.pymybatis` | 2.1.0 |
-| `spring.ai` AI 模块 | 2.1.0 |
-| `spring.langchain` LangChain 模块 | 2.1.0 |
+| `spring` 框架 API | 2.2.0 |
+| `spring.orm.pymybatis` | 2.2.0 |
+| `spring.ai` AI 模块 | 2.2.0 |
+| `spring.langchain` LangChain 模块 | 2.2.0 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -227,7 +228,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | 应用事件 | ✅ 可用 | `ApplicationEvent`、`@EventListener`、同步有序发布和异步监听 |
 | 内嵌 ORM + DDL Auto | ✅ 可用 | PyMyBatis + JPA ddl-auto 自动建表(create/update/validate)，支持 XML/注解 SQL、事务、缓存 |
 | 本地事务 | ✅ 可用 | `@Transactional` 支持七种 Spring 传播模式 |
-| JWT 与方法安全 | ✅ 可用 | access/refresh token、`@Authenticate`、角色/权限授权、401/403 映射 |
+| JWT 与方法安全 | ✅ 可用 | access/refresh token、`@Authenticate`、前置/后置授权、401/403 映射 |
 | 重试/异步 | ✅ 可用 | 受管 Bean 的退避重试、恢复方法和 Future/Task 异步调度 |
 | Redis/缓存 | ✅ 可用 | 分布式锁、KV/Hash/List/Set/Counter，需要 Redis 服务 |
 | RabbitMQ | ✅ 可用 | `@RabbitListener` 自动注册并后台消费，`RabbitTemplate` 发送 |
@@ -238,7 +239,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | API Gateway | ✅ 可用 | 轻量 ASGI/WSGI 网关，路由转发、路径重写、过滤器链、负载均衡 |
 | Prometheus 监控 | ✅ 可用 | Counter/Gauge/Histogram 指标暴露 |
 | Feign 声明式 HTTP | ✅ 可用 | 声明式接口、Fallback 降级、自动传播 XID 和 trace 头 |
-| 高级 AOP | ✅ 可用 | 限流、熔断、幂等、审计、锁、指标、追踪、缓存 |
+| 高级 AOP | ✅ 可用 | 声明式切面、限流、熔断、幂等、审计、锁、指标、追踪、缓存 |
 | AI 模块 | ✅ 可用 | ChatClient/ChatModel/EmbeddingModel/Advisor/Tools，OpenAI/Ollama/DeepSeek/Moonshot 适配 |
 | LangChain 模块 | ✅ 可用 | Chains/Agents(6 种)/Memory/Retrievers/VectorStores + 30+ 提供商，双向适配器 |
 | LangGraph 模块 | ✅ 可选 | 官方 LangGraph 状态图、条件路由、人工中断、持久化 checkpointer 和注解工作流 |
@@ -871,7 +872,7 @@ class ScheduledTasks:
         print("Current time:", time.time())
 ```
 
-**边界要点**：`max_retries=3` 包含首次调用；`@Async` 同步方法返回 `Future`；`@Scheduled` 多 worker 会重复执行。
+**边界要点**：`max_retries=3` 包含首次调用；重试耗尽可用 `@Recover` 按异常类型兜底；`@Async` 同步方法返回 `Future`；`@Scheduled` 多 worker 会重复执行。声明式切面、后置鉴权和恢复方法的完整小白示例见 [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md)。
 
 ### 5.10 安全、Cloud 与消息注解
 
@@ -879,6 +880,7 @@ class ScheduledTasks:
 |------|----------|--------------|
 | `@Authenticate` | 校验 JWT 并建立安全上下文 | 受管 Bean 实际执行；HTTP 控制器自动读取 `Authorization: Bearer ...` |
 | `@PreAuthorize` | 按角色/权限表达式授权 | 受管 Bean 实际执行；未认证返回 401，权限不足返回 403 |
+| `@PostAuthorize` | 根据方法返回值授权 | 受管 Bean 返回后执行；支持 `returnObject` / `#returnObject` |
 | `@Secured` | 按任一角色授权 | 受管 Bean 实际执行 |
 | `@SentinelResource` | 限流、业务异常 fallback | 受管 Bean 方法会包装；已内嵌限流熔断引擎 |
 | `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法调用 Seata manager |
@@ -1231,6 +1233,22 @@ def call_remote(self):
 
 **只对幂等操作开启自动重试**（如读操作）。写操作必须先设计幂等键。
 
+重试耗尽后可以使用 `@Recover`：
+
+```python
+from spring.annotations import Recover, Retryable
+
+@Retryable(value=(ConnectionError,), max_attempts=3, backoff=200)
+def call_remote(self, key):
+    raise ConnectionError("offline")
+
+@Recover(ConnectionError)
+def recover_remote(self, error, key):
+    return {"key": key, "status": "degraded", "reason": str(error)}
+```
+
+恢复方法选择、异步用法和常见错误见 [AOP / 后置鉴权 / 重试恢复指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md)。
+
 ### 11.3 @Async & @Scheduled
 
 ```python

{springbootai-2.1.0 → springbootai-2.2.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # 发行名 springbootAI（PyPI 包名，pip install springbootAI）；导入包名仍为 spring
 name = "springbootAI"
-version = "2.1.0"
+version = "2.2.0"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"
@@ -101,8 +101,8 @@ excel = ["openpyxl==3.1.5"]
 # 依赖清单同步自 requirements-ai.txt（所有版本号 == 已测试验证）
 # ========================================
 ai = [
-    "langchain-openai==1.4.1",
-    "langchain-core==1.5.1",
+    "langchain-openai==1.4.2",
+    "langchain-core==1.5.4",
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",
@@ -117,8 +117,8 @@ ai = [
 # 详见 doc/LANGCHAIN_MODULE.md
 # ========================================
 langchain = [
-    "langchain-openai==1.4.1",
-    "langchain-core==1.5.1",
+    "langchain-openai==1.4.2",
+    "langchain-core==1.5.4",
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",
@@ -191,8 +191,8 @@ full = [
     # Excel
     "openpyxl==3.1.5",
     # AI 模块（对齐 springbootAI[ai]）
-    "langchain-openai==1.4.1",
-    "langchain-core==1.5.1",
+    "langchain-openai==1.4.2",
+    "langchain-core==1.5.4",
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",

{springbootai-2.1.0 → springbootai-2.2.0}/requirements-ai.txt

@@ -7,21 +7,21 @@
 #
 # 安装方式（按需）：
 #   pip install -r requirements-ai.txt          # 全量
-#   pip install langchain-openai==1.4.1         # 仅 OpenAI 适配
+#   pip install langchain-openai==1.4.2         # 仅 OpenAI 适配
 #
 # 推荐 Python: 3.10+（CI 测试 3.10 / 3.11 / 3.12）
 # 所有固定版本均经过本仓库测试与依赖漏洞扫描
 # ========================================
 
 # LangChain 核心（1.x 架构，BaseChatModel / Embeddings / Runnable 接口）
-langchain-core==1.5.1
+langchain-core==1.5.4
 
 # LangChain classic（LLMChain / ConversationChain / initialize_agent 等经典 API）
 # langchain 1.x 把经典 Chain/Agent 迁到了 langchain-classic 包
 langchain-classic==1.0.8
 
 # OpenAI 兼容模型适配（OpenAI / Azure / DeepSeek / Moonshot）
-langchain-openai==1.4.1
+langchain-openai==1.4.2
 
 # 文档切分器（RecursiveCharacterTextSplitter / CharacterTextSplitter）
 langchain-text-splitters==1.1.2

{springbootai-2.1.0 → springbootai-2.2.0}/spring/__init__.py

@@ -5,7 +5,7 @@ from .config import *
 from .utils import *
 from .main import create_app, run, SpringApplication, run_cli
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-2.1.0 → springbootai-2.2.0}/spring/ai/__init__.py

@@ -47,7 +47,7 @@ from spring.ai.resilience import (
 from spring.ai.observability import AIMetrics, ai_metrics
 from spring.ai.autoconfig import AIProperties, bind_ai_config, configure_ai
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 __all__ = [
     # core

{springbootai-2.1.0 → springbootai-2.2.0}/spring/annotations/__init__.py

@@ -13,6 +13,13 @@ from .core import (
     DeleteMapping,
     Service,
     Component,
+    Aspect,
+    Pointcut,
+    Before,
+    After,
+    Around,
+    AfterReturning,
+    AfterThrowing,
     Repository,
     Autowired,
     Qualifier,
@@ -42,6 +49,7 @@ from .core import (
     Transactional,
     Cacheable,
     Retryable,
+    Recover,
     Async,
     Scheduled,
     AsyncResult,
@@ -56,6 +64,7 @@ from .core import (
     Validate,
     Trace,
     PreAuthorize,
+    PostAuthorize,
     Secured,
     Authenticate,
 )
@@ -127,6 +136,13 @@ __all__ = [
     "DeleteMapping",
     "Service",
     "Component",
+    "Aspect",
+    "Pointcut",
+    "Before",
+    "After",
+    "Around",
+    "AfterReturning",
+    "AfterThrowing",
     "Repository",
     "Autowired",
     "Qualifier",
@@ -154,6 +170,7 @@ __all__ = [
     "Transactional",
     "Cacheable",
     "Retryable",
+    "Recover",
     "Async",
     "Scheduled",
     "AsyncResult",
@@ -169,6 +186,7 @@ __all__ = [
     "Trace",
     # 安全注解
     "PreAuthorize",
+    "PostAuthorize",
     "Secured",
     "Authenticate",
     # Spring Cloud 注解

{springbootai-2.1.0 → springbootai-2.2.0}/spring/annotations/core.py

@@ -230,6 +230,76 @@ class Component(SpringAnnotation):
         super().__init__(value=value)
 
 
+class Aspect(Component):
+    """Declare a component whose methods contain AOP advice."""
+
+    _annotation_type = "aspect"
+
+
+class Pointcut(SpringAnnotation):
+    """Declare a reusable pointcut expression on an aspect method."""
+
+    _annotation_type = "pointcut"
+
+    def __init__(self, value: str):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("Pointcut value must be a non-empty string")
+        super().__init__(value=value.strip())
+
+
+class _AdviceAnnotation:
+    def _init_advice(self, value: str = "", *, pointcut: Optional[str] = None):
+        expression = pointcut if pointcut is not None else value
+        if not isinstance(expression, str) or not expression.strip():
+            raise ValueError("Advice pointcut must be a non-empty string")
+        SpringAnnotation.__init__(self, value=expression.strip())
+
+
+class Before(_AdviceAnnotation, SpringAnnotation):
+    """Run advice before a matched method."""
+
+    _annotation_type = "advice"
+
+    def __init__(self, value: str = "", *, pointcut: Optional[str] = None):
+        self._init_advice(value, pointcut=pointcut)
+
+
+class After(Before):
+    """Run advice after a matched method, including exceptional completion."""
+
+
+class Around(Before):
+    """Wrap a matched method with a ``ProceedingJoinPoint``."""
+
+
+class AfterReturning(Before):
+    """Run advice after a matched method returns successfully."""
+
+    def __init__(
+        self,
+        value: str = "",
+        *,
+        pointcut: Optional[str] = None,
+        returning: str = "result",
+    ):
+        self._init_advice(value, pointcut=pointcut)
+        self.returning = returning
+
+
+class AfterThrowing(Before):
+    """Run advice after a matched method raises an exception."""
+
+    def __init__(
+        self,
+        value: str = "",
+        *,
+        pointcut: Optional[str] = None,
+        throwing: str = "exception",
+    ):
+        self._init_advice(value, pointcut=pointcut)
+        self.throwing = throwing
+
+
 class Repository(SpringAnnotation):
     _annotation_type = "component"
 
@@ -595,6 +665,35 @@ class Retryable(SpringAnnotation):
         )
 
 
+class Recover(SpringAnnotation):
+    """Mark a method as a fallback for an exhausted ``@Retryable`` call."""
+
+    _annotation_type = "recover"
+
+    def __new__(cls, *args, **kwargs):
+        # ``@Recover(SomeError)`` uses an exception class as configuration,
+        # not as the decorator target understood by SpringAnnotation.__new__.
+        if args and isinstance(args[0], type) and issubclass(args[0], Exception):
+            return object.__new__(cls)
+        return super().__new__(cls, *args, **kwargs)
+
+    def __init__(
+        self,
+        value: Optional[Union[Type[Exception], Tuple[Type[Exception], ...]]] = None,
+    ):
+        if value is None:
+            exception_types = None
+        elif isinstance(value, type) and issubclass(value, Exception):
+            exception_types = (value,)
+        elif isinstance(value, tuple) and value and all(
+            isinstance(item, type) and issubclass(item, Exception) for item in value
+        ):
+            exception_types = value
+        else:
+            raise TypeError("Recover value must be an exception type or non-empty tuple")
+        super().__init__(value=exception_types)
+
+
 class Async(SpringAnnotation):
     _annotation_type = "aop"
 
@@ -832,6 +931,17 @@ class PreAuthorize(SpringAnnotation):
         super().__init__(value=value)
 
 
+class PostAuthorize(SpringAnnotation):
+    """Authorize a method after evaluating its return value."""
+
+    _annotation_type = "security"
+
+    def __init__(self, value: str):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("PostAuthorize value must be a non-empty expression")
+        super().__init__(value=value.strip())
+
+
 class Secured(SpringAnnotation):
     """
     角色权限控制注解

springbootai-2.2.0/spring/aop/__init__.py

@@ -0,0 +1,10 @@
+from .proxy_factory import ProxyFactory
+from .method_interceptor import MethodInterceptor
+from .aspect import JoinPoint, ProceedingJoinPoint
+
+__all__ = [
+    "ProxyFactory",
+    "MethodInterceptor",
+    "JoinPoint",
+    "ProceedingJoinPoint",
+]