Solon v3.8 更新与兼容说明

兼容说明

（1）for solon 仓库

重要变化：

• ScopeLocal 接口（实现了 ThreadLocal 到 ScopedValue 兼容）

新特性展示：

public class Demo {
   static ScopeLocal<String> LOCAL = ScopeLocal.newInstance();

   public void test(){
       LOCAL.with("test", ()->{
           System.out.println(LOCAL.get());
       });
   }
}

（2）for solon-ai 仓库

重要变化：

• mcp-java-sdk 升为 v0.17 （支持 2025-06-18 版本协议）
• 添加 mcp-server McpChannel.STREAMABLE_STATELESS 通道支持（集群友好）
• 添加 mcp-server 异步支持

新特性展示：1.MCP 无状态会话（STREAMABLE_STATELESS）和 2.CompletableFuture 异步MCP工具

@McpServerEndpoint(channel = McpChannel.STREAMABLE_STATELESS, mcpEndpoint = "/mcp1")
public class McpServerTool {
    @ToolMapping(description = "查询天气预报", returnDirect = true)
    public CompletableFuture<String> getWeather(@Param(description = "城市位置") String location) {
        return CompletableFuture.completedFuture("晴，14度");
    }
}

（3）for solon-flow 仓库（有破坏性变更）

重要变化：

• 第六次预览
• 取消“有状态”、“无状态”概念。
• solon-flow 回归通用流程引擎（分离“有状态”的概念）。
• 新增 solon-flow-workflow 为工作流性质的封装（未来可能会有 dataflow 等）。

兼容变化对照表：

FlowStatefulService 到 WorkflowService 的接口变化对照表：

新特性预览：Graph 硬编码方式（及修改能力增强）

//硬编码
Graph graph = Graph.create("demo1", "示例", spec -> {
    spec.addStart("start").title("开始").linkAdd("01");
    spec.addActivity("n1").task("@AaMetaProcessCom").linkAdd("end");
    spec.addEnd("end").title("结束");
});

//修改
Graph graphNew = Graph.copy(graph, spec -> {
    spec.getNode("n1").linkRemove("end").linkAdd("n2"); //移掉 n1 连接；改为 n2 连接
    spec.addActivity("n2").linkAdd("end");
});

新特性预览：FlowContext:lastNodeId （计算的中断与恢复）。参考：https://solon.noear.org/article/1246

flowEngine.eval(graph, context.lastNodeId(), context);
//...（从上一个节点开始执行）
flowEngine.eval(graph, context.lastNodeId(), context);

新特性预览：WorkflowService（替代 FlowStatefulService）

WorkflowService workflow = WorkflowService.of(engine, WorkflowDriver.builder()
        .stateController(new ActorStateController()) 
        .stateRepository(new InMemoryStateRepository()) 
        .build());


//1. 取出任务
Task task = workflow.getTask(graph, context);

//2. 提交任务
workflow.postTask(task.getNode(), TaskAction.FORWARD, context);

具体更新

• 插件 solon-flow 第六次预览
• 新增 solon-flow-workflow 插件（替代 FlowStatefulService）
• 新增 solon-java25 仓库（提供 ScopedValue 适配）
• 添加 solon ScopeLocal 接口（用于 ThreadLocal 到 ScopedValue 兼容）
• 添加 solon Solon.start(Class, MultiMap) 方法
• 添加 solon ThreadsUtil:newVirtualThreadFactory 方法
• 添加 solon ContextHolder:currentWith 方法，替代 currentSet（标为弃用）
• 添加 solon Controller:remoting 属性（可替代 @Remoting 注解）
• 添加 solon 非依赖关系的 bean 异步初始化（@Init(async=true)）
• 添加 solon Stringable 接口
• 添加 solon 'env.use' 配置支持（相对 'env'，它与 'env.on' 协作时不会冲突）
• 添加 solon 'server.session.cookieHttpOnly' 配置支持（默认为 true）
• 添加 solon Context.cookieSet(...,httpOnly) 方法
• 添加 solon-test HttpTester protocol 参数支持（方便 https 或 http 切换测试）
• 添加 solon-serialization JsonPropsUtil2.dateAsFormat 添加 java.sql.Timestamp 类型支持
• 添加 solon-config-yaml 依赖 solon-config-snack4 避免单个引入时忘掉
• 添加 solon-net-httputils HttpSslSupplierAny（方便无限制的 ssl 使用，但不建议）
• 添加 solon-web-rx RxEntity 类（方便对接 mcp-sdk）
• 添加 solon-server 会话状态的 cookie httpOnly 配置（默认为 false）
• 添加 solon-server-tomcat ssl 适配支持
• 添加 solon-security-validation ValidatorFailureHandlerI18n 支持验证注解的国际化处理 添加 solon-expression SnelParser 类，为 TemplateParser 和 EvaluateParser 提供出入口和占位符配置
• 添加 solon-flow FlowContext:lastNode() 方法（最后一个运行的节点）
• 添加 solon-flow FlowContext:lastNodeId() 方法（最后一个运行的节点Id）
• 添加 solon-flow Node.getMetaAs, Link.getMetaAs 方法
• 添加 solon-flow NodeSpec:linkRemove 方法（增强修改能力）
• 添加 solon-flow Graph:create(id,title,consumer) 方法
• 添加 solon-flow Graph:copy(graph,consumer) 方法（方便复制后修改）
• 添加 solon-flow GraphSpec:getNode(id) 方法
• 添加 solon-flow GraphSpec:addLoop(id) 方法替代 addLooping（后者标为弃用）
• 添加 solon-flow FlowEngine:eval(Graph, ..) 系列方法
• 添加 solon-ai FunctionPrompt:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai FunctionResource:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai FunctionTool:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai-core ChatMessage:toNdjson,fromNdjson 方法（替代 ChatSession:toNdjson, loadNdjson），新方法机制上更自由
• 添加 solon-ai-core ToolSchemaUtil.jsonSchema Publisher 泛型支持
• 添加 solon-ai-mcp mcp-java-sdk v0.17 适配（支持 2025-06-18 版本协议）
• 添加 solon-ai-mcp mcp-server 异步支持
• 添加 solon-ai-mcp mcp-server streamable_stateless 支持
• 添加 solon-ai-mcp Tool,Resource,Prompt 对 org.reactivestreams.Publisher 异步返回支持
• 添加 solon-ai-mcp McpServerHost 服务宿主接口，用于隔离有状态与无状态服务
• 添加 solon-ai-mcp McpChannel.STREAMABLE_STATELESS （服务端）无状态会话
• 添加 solon-ai-mcp McpClientProvider:customize 方法（用于扩展 roots, sampling 等）
• 添加 solon-ai-mcp mcpServer McpAsyncServerExchange 注入支持（用于扩展 roots, sampling 等）
• 优化 solon api-version 版本匹配
• 优化 solon SnelUtil snel 表达式缺参数时异常提示（避免配错名字）
• 优化 solon ParamWrap:getName 改用 ParamSpec.getAlias。加 '@Param(name=xxx)' 注解可生效
• 优化 solon-net-httputils SslContextBuilder
• 优化 solon-expression EvaluateParser 支持定义占位符（可支持 {xxx} 表达式）
• 优化 solon-expression TemplateParser 支持定义占位符（可支持 {xxx} 表达式）
• 优化 solon-expression LRUCache 性能（提高缓存性能）
• 优化 solon-ai-dialect-openai claude 兼容性
• 优化 solon-ai-mcp mcp StreamableHttp 模式下 服务端正常返回时 客户端异常日志打印的情况* 优化 solon-flow eval(Node startNode) 处理，改为从 root 开始恢复到 start 再开始执行（恢复过程中，不会执行任务）
• 优化 solon-flow FlowEngine:eval(Node startNode) 处理，改为从 root 开始恢复到 start 再开始执行（恢复过程中，不会执行任务）
• 调整 nami NamiAttachment 切换为 ScopeLocal 接口实现
• 调整 solon ContextHolder 切换为 ScopeLocal 接口实现
• 调整 solon RunHolder：parallelExecutor 改为 newFixedThreadPool
• 调整 solon-data TranExecutorDefault 切换为 ScopeLocal 接口实现
• 调整 local-solon-cloud-plugin 的 config 和 i18n 服务，如果没有 group 配置，则文件不带 group 前缀（之前默认给了 DEFAULT_GROUP 组名，显得复杂）
• 调整 rocketmq-solon-clouud-plugin 的适配，事件属性不再加 '!' （并兼容旧格式）
• 调整 aliyun-ons-solon-clouud-plugin 的适配，事件属性不再加 '!' （并兼容旧格式）
• 调整 rocketmq5-solon-clouud-plugin 的适配，事件属性不再加 '!' （并兼容旧格式）。添加 sql92 过滤支持
• 调整 solon-flow 移除 Activity 节点预览属性 "$imode" 和 "$omode"
• 调整 solon-flow Activity 节点流出改为自由模式（可以多线流出：无条件直接流出，有条件检测后流出）
• 调整 solon-flow Node.getMeta 方法返回改为 Object 类型（并新增 getMetaAs）
• 调整 solon-flow Evaluation:runTest 改为 runCondition
• 调整 solon-flow FlowContext:incrAdd,incrGet 标为弃用（上下文数据为型只能由输入侧决定）
• 调整 solon-flow Condition 更名为 ConditionDesc
• 调整 solon-flow Task 更名为 ConditionDesc
• 调整 solon-flow XxxDecl 命名风格改为 XxxSpec
• 调整 solon-flow GraphDecl.parseByXxx 命名风格改为 GraphSpec.fromXxx
• 调整 solon-flow Graph.parseByXxx 命名风格改为 Graph.fromXxx
• 调整 solon-ai-mcp getResourceTemplates、getResources 不再共享注册
• 调整 solon-ai-mcp McpServerManager 内部接口更名为 McpPrimitivesRegistry （MCP 原语注册器）
• 调整 solon-ai-mcp McpClientProvider 默认不启用心跳机制（随着 mcp-sdk 的成熟，server 都有心跳机制了）
• 修复 solon IndexFiles 路径表达式的兼容问题（添加转换 *->@、:->!）
• 修复 solon ParamWrap:getName 加 '@Param(name=xxx)' 注解时没有生效的问题（v3.7.0 出现）
• 修复 solon-docs-openapi2 返回类型中泛型失效的问题（v3.7.0 出现）
• snack4 升为 4.0.20
• jackson 升为 2.19.2
• liquor 升为 1.6.6
• asm 升为 9.9