Solon

https://solon.noear.org
Admin
Solon is a next-generation Java enterprise application framework that delivers high concurrency, low...
Tokens:1,798,100
Snippets:32,883
Trust Score:3.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Solon Application Examples

Source: https://solon.noear.org/

Demonstrates basic controller setup using both manual routing and annotation-based mapping in Java, Groovy, and Kotlin.

```java
@Controller
public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args, app -> {
            //手写模式
            app.router().get("/hello1", ctx -> ctx.output("Hello world!"));
        });
    }

    //注解模式（示例，一个方法可支持多种 method）
    @Get
    @Socket
    @Mapping("/hello2")
    public String hello2(String name) {
        return String.format("Hello %s!", name);
    }
}
```

```groovy
@Controller
class App {
    static void main(String[] args){
        Solon.start(App.class, args, app->{
            //手写模式
            app.router().get("/hello1", ctx -> ctx.output("Hello world!"))
        })
    }
    
    //注解模式（示例，一个方法可支持多种 method）
    @Get
    @Socket
    @Mapping("/hello2")
    String hello(@Param(defaultValue = "world") String name) {
        return String.format("Hello %s!", name)
    }
}
```

```kotlin
@Controller
class App {
    //注解模式（示例，一个方法可支持多种 method）
    @Get
    @Socket
    @Mapping("/hello2")
    fun hello(@Param(defaultValue = "world") name: String): String {
        return String.format("Hello %s!", name)
    }
}

fun main(args: Array<String>) {
    Solon.start(App::class.java, args) { app ->
        //手写模式
        app.router().get("/hello1") { ctx -> ctx.output("Hello world!") }
    }
}
```

--------------------------------

### SolonProps Configuration Example

Source: https://solon.noear.org/api/org/noear/solon/package-summary.html

Demonstrates how to manually get configuration values using Solon.cfg() and access properties like debug mode, drift mode, and specific configurations like 'water.logger' and 'db1'. It also explains the priority of configuration sources.

```java
// 手动获取配置模式（容器自动模式可用: @Inject("${water.logger}")）
// 配置的优先级：命令参数-> 环境配置-> 系统配置-> 应用配置 （越动态的越优化）
Solon.cfg()
Solon.cfg().isDebugMode()
Solon.cfg().isDriftMode()
Solon.cfg().get("water.logger")
Solon.cfg().getProp("db1")
```

--------------------------------

### Web Client Setup

Source: https://solon.noear.org/article/857

Install and configure the STOMP client for web browsers.

```bash
npm install @stomp/stompjs@7.0.0
```

```javascript
import { Client, Versions } from '@stomp/stompjs';
const stompClient = new Client({
    webSocketFactory: ()=> new WebSocket('ws://127.0.0.1:8080/chat?user=demo'),
    onConnect: function (frame) {
        //订阅：所有主题消息（只示例）
        stompClient.subscribe('/topic/**', function (resp) {
            console.log(resp.body);
        });

        //订阅：接收 app 返回的错误
        stompClient.subscribe('/user/app/errors', function (resp) {
            console.log(resp.body);
        });
    }
stompClient.activate()

stompClient.publish({
    destination: "/app/hello",
    body: "hi"
});
```

--------------------------------

### Method Details: setup

Source: https://solon.noear.org/api/org/noear/solon/boot/jetty/JettyServer.html

Details for the setup method.

```java
protected void setup(java.lang.String host,
                     int port)
              throws java.io.IOException
```

--------------------------------

### 定义 start 节点

Source: https://solon.noear.org/article/903?format=md

流程图的入口节点，每个流程必须包含且仅包含一个 start 节点。

```yaml
id: demo1
layout:
  - type: start
  - type: end
```

--------------------------------

### Application Startup and Configuration Examples

Source: https://solon.noear.org/article/176

Examples of passing startup parameters and system properties when launching a Solon application JAR.

```bash
java -jar demo.jar --env=dev --drift=1
```

```bash
java -Dsolon.env=dev -jar demo.jar
```

```bash
java -jar demo.jar --solon.env=dev
```

```bash
java -Dserver.port=8081 -jar demo.jar
```

```bash
java -jar demo.jar --server.port=8081
```

--------------------------------

### start Method

Source: https://solon.noear.org/api/org/noear/solon/boot/websocket/netty/NettyWsServer.html

Starts the server with the given host and port. Implements the start method from the ServerLifecycle interface.

```java
public
void
start(java.lang.String
host,
int
port)
throws java.lang.Throwable
```

--------------------------------

### examples Method

Source: https://solon.noear.org/api/com/layjava/docs/javadoc/solon/wrap/ApiImplicitParamImpl.html

The implementation of the examples() method.

```java
public
io.swagger.annotations.Example
examples()
```

--------------------------------

### start Method

Source: https://solon.noear.org/api/org/noear/solon/hotplug/PluginPackage.html

Starts the plugin package.

```java
public
PluginPackage
start()
```

--------------------------------

### Mapper Configuration Examples

Source: https://solon.noear.org/article/20

Examples for configuring XML mappers and Java interface mappers.

```yaml
mybatis.db1:
    mappers: 
        - "classpath:demo4021/**/mapper.xml"
```

```yaml
mybatis.db1:
    mappers: 
        - "demo4021.**.mapper.*"
```

--------------------------------

### Method Details: start

Source: https://solon.noear.org/api/org/noear/solon/boot/vertx/VxHttpServerComb.html

Detailed description of the start method.

```java
public void start(java.lang.String host,
 int port)
           throws java.lang.Throwable
```

--------------------------------

### example Method

Source: https://solon.noear.org/api/com/layjava/docs/javadoc/solon/wrap/ApiImplicitParamImpl.html

The implementation of the example() method.

```java
public
java.lang.String
example()
```

--------------------------------

### Method Detail: start

Source: https://solon.noear.org/api/org/noear/solon/hotplug/PluginManager.html

Details for the start method, including parameters.

```java
public static void start(java.lang.String name)
```

--------------------------------

### Method Details: start

Source: https://solon.noear.org/api/org/noear/solon/boot/jetty/JettyServer.html

Details for the start method, implementing ServerLifecycle.start.

```java
public void start(java.lang.String host,
                  int port)
           throws java.lang.Throwable
```

--------------------------------

### Example: Data Plugin Implementation

Source: https://solon.noear.org/article/58?format=md

A practical example showing how a data plugin registers a transaction interceptor and configures its priority.

```java
public class DataSolonPlugin implements Plugin {
    @Override
    public void start(AppContext context) {
        if (Solon.app().enableTransaction()) {
            context.beanInterceptorAdd(Tran.class, new TranInterceptor(), 120);
        }
    }
}
```

```properties
solon.plugin=org.noear.solon.data.integration.DataSolonPlugin
solon.plugin.priority=3
```

--------------------------------

### Configuring Data Sources via YAML

Source: https://solon.noear.org/article/anyline

Example configuration for data sources using a static configuration file.

```yaml
#默认数据源
anyline:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:33306/simple
    user-name: root
    password: root
  datasource-list: crm,erp,sso
  crm:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:33306/simple_crm
    username: root
    password: root
  erp:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:33306/simple_erp
    username: root
    password: root
  sso:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:33306/simple_sso
    username: root
    password: root
```

--------------------------------

### get Method (Expression and AddStarts)

Source: https://solon.noear.org/api/org/noear/solon/core/util/PathMatcher.html

Gets a PathMatcher instance for a given expression with an option to add starts.

```java
public static PathMatcher get(java.lang.String expr,
                              boolean addStarts)
```

--------------------------------

### Basic Application Setup

Source: https://solon.noear.org/article/1134

Standard entry point and controller mapping for a Solon application.

```java
public class DemoApp {
    public static void main(String[] args) {
        Solon.start(DemoApp.class, args);
    }
}

@Controller
public class DemoController{
    @Mapping("/hello")
    public String hello(){
        return "Hello world!";
    }
}
```

--------------------------------

### test2

Source: https://solon.noear.org/api/webapp/demo2_mvc/Param4Controller.html

Example of a GET request with a Context parameter.

```java
@Get
 @Mapping(value="test2")
public
java.util.Map
test2(Context
ctx)
throws java.io.IOException
```

--------------------------------

### get Method (expr, addStarts)

Source: https://solon.noear.org/api/org/noear/solon/core/util/PathAnalyzer.html

Deprecated method to get a PathAnalyzer instance with an expression and a flag for adding starts.

```java
public static PathAnalyzer get(java.lang.String expr,
 boolean addStarts)
```

--------------------------------

### Initialize and Use HarnessEngine

Source: https://solon.noear.org/article/1419

Demonstrates initializing the HarnessEngine with system prompts, tool permissions, and model configurations, followed by executing prompts using main and sub-agent patterns.

```java
import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.ai.chat.ChatConfig;
import org.noear.solon.ai.harness.HarnessEngine;
import org.noear.solon.ai.harness.agent.AgentDefinition;
import org.noear.solon.ai.harness.agent.ToolName;
import org.noear.solon.ai.talents.mount.MountDir;
import org.noear.solon.ai.talents.mount.MountType;

public class DemoApp {
    public static void main(String[] arg) throws Throwable {
        //--- 1. 初始化
        HarnessEngine engine = HarnessEngine.of("/data/work/", ".tmp")
                .systemPrompt("xxx")
                .sessionProvider(InMemoryAgentSession::of)
                .toolsAdd(ToolName.TOOL_ALL_FULL) //设定工具权限
                .disallowedToolsAdd(ToolName.TOOL_ALL_FULL)
                .mountAdd(MountDir.builder()
                        .alias("@global-agents")
                        .type(MountType.AGENTS)
                        .path("~/.soloncode/agents/")
                        .primary(true)
                        .build())
                .modelAdd(new ChatConfig().then(slf -> {
                    slf.setApiUrl("https://api.deepseek.com");
                    slf.setApiKey("sk-***");
                    slf.setModel("deepseek-v4-flash");
                })) //设定大模型配置
                .extensionAdd((name, builder) -> {
                    //...
                })
                .build();

        //engine.addMcpServer("name", ...);

        //--- 用主代理执行
        useCsae1(engine, "hello");

        //--- 动态创建子代理执行（好处理可以动态创建不同的工具权限）
        useCase2(engine, "hello");

    }

    private static void dynamicUpdate1(HarnessEngine engine) {
        //动态更新示例
    }

    private static void useCsae1(HarnessEngine engine, String prompt) throws Throwable {
        AgentSession session = engine.getSession("default");

        //--- 用主代理模式
        engine.prompt(prompt)
                .session(session) //没有，则为临时会话
                .options(o -> {

                    //切换大模型
                    //o.chatModel(engine.getMainModel());

                    //按需，动态指定工作区（没有，则为默认工作区）
                    o.toolContextPut(HarnessEngine.ATTR_CWD, "xxx");
                })
                .call();
    }

    private static void useCase2(HarnessEngine engine, String prompt) throws Throwable {
        AgentSession session = engine.getSession("default");

        //动态定义智能体
        AgentDefinition definition = new AgentDefinition();
        definition.setSystemPrompt("xxx"); //系统提示词
        definition.getMetadata().addTools(ToolName.TOOL_BASH); //工具权限

        ReActAgent subagent = engine.createSubagent(definition).build();
        subagent.prompt(prompt)
                .session(session) //没有，则为临时会话
                .options(o -> {
                    //按需，动态指定工作区（没有，则为默认工作区）
                    o.toolContextPut(HarnessEngine.ATTR_CWD, "xxx");
                })
                .call();
    }
}
```

--------------------------------

### Method Details: start

Source: https://solon.noear.org/api/org/noear/solon/boot/smarthttp/SmHttpServerComb.html

Detailed description of the start method.

```java
public void start(java.lang.String host,
 int port)
 throws java.lang.Throwable
```

--------------------------------

### Get Serializer

Source: https://solon.noear.org/api/org/noear/solon/core/serialize/SerializerManager.html

Finds a serializer by its name. Example usage provided.

```java
public <T> Serializer<T> get(java.lang.String name)
```

```java
Serializer<String> get("@json");
 Serializer<String> get("fastjson-serializer");
```

--------------------------------

### Configuration Examples

Source: https://solon.noear.org/article/156?format=md

YAML configuration for setting up the MQTT server and client options.

```yml
solon.app:
  group: demo       #配置服务使用的默认组
  name: helloproducer    #发现服务使用的应用名

solon.cloud.mqtt.event:
  server: "tcp://localhost:41883"   #mqtt服务地址
```

```yml
solon.app:
  group: demo       #配置服务使用的默认组
  name: helloproducer    #发现服务使用的应用名

solon.cloud.mqtt.event:
  server: "tcp://localhost:41883"   #mqtt服务地址
  client:  #对应 MqttConnectOptions 类的字段
    connectionTimeout: 1000
    keepAliveInterval: 100
```

--------------------------------

### Manual Skill Installation Paths

Source: https://solon.noear.org/article/1408

Target directories for manually installing skill packages.

```text
~/.soloncode/skills/
```

```text
.soloncode/skills/
```

--------------------------------

### SolonApp Initialization

Source: https://solon.noear.org/article/420

How to start a Solon application and obtain the SolonApp instance.

```APIDOC
## Solon.start(Class<?> source, String[] args, Consumer<SolonApp> init)

### Description
Starts the Solon application and provides the SolonApp instance via a callback for initialization.

### Method
Static Method

### Parameters
- **source** (Class<?>) - Required - The main application class annotated with @SolonMain.
- **args** (String[]) - Required - Command line arguments.
- **init** (Consumer<SolonApp>) - Optional - A callback function to configure the app instance upon startup.
```

--------------------------------

### Initialize and Configure HarnessEngine

Source: https://solon.noear.org/article/1471

Demonstrates how to build a HarnessEngine instance with memory providers and runtime memory management methods.

```java
HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
 .sessionProvider(InMemoryAgentSession::of)
 .memoryProvider(new MyMemoryProvider())
 .memoryEnabled(true)
 .memoryRelevanceCount(6)
 .memoryPriorityCount(5)
 .memorySummaryLength(80)
 .sessionWindowSize(8)
 .compressionThreshold(40, 0.75)
 .build();

// 运行时关闭心智记忆
engine.setMemoryEnabled(false);

// 运行时调整记忆检索数量
engine.setMemoryRelevanceCount(10);

// 获取 MemoryTalent 实例直接操作（如注册拦截器）
engine.getMemoryTalent(); // 返回 MemoryTalent 实例
```

--------------------------------

### get Method

Source: https://solon.noear.org/api/webapp/demo2_mvc/SessionController.html

The get method of SessionController, which takes a Context and returns an Object. It is mapped to 'get'.

```java
@Mapping(value="get")
public java.lang.Object get(Context ctx)
```

--------------------------------

### 运行时指定 solon.config.add 扩展配置

Source: https://solon.noear.org/article/894

通过命令行参数在启动时动态添加扩展配置文件。

```bash
java -jar demo.jar -solon.config.add=file:config/demo.yml,classpath:config/demo.yml,config/demo.yml
```

```bash
java -Dsolon.config.add=file:config/demo.yml,classpath:config/demo.yml,config/demo.yml -jar demo.jar
```

--------------------------------

### start

Source: https://solon.noear.org/api/org/noear/solon/core/AppContext.html

Start (generally executed after plugins start and application scan is complete).

```java
public void start()
```

--------------------------------

### Initialize Solon application

Source: https://solon.noear.org/article/1372?format=md

Standard entry point for starting a Solon application.

```java
public class DemoApp {
    public static void main(String[] args) throws Exception{
        Solon.start(DemoApp.class, args).block();
    }
}
```

--------------------------------

### start Method

Source: https://solon.noear.org/api/org/noear/solon/boot/socketd/integration/SocketdPlugin.html

The start method of the SocketdPlugin, responsible for starting the plugin. It is a placeholder for compatibility.

```java
public
void start(AppContext context)
           throws java.lang.Throwable
```

--------------------------------

### Get Annotation Definition

Source: https://solon.noear.org/api/org/noear/solon/annotation/Get.html

The definition of the @Get annotation, specifying its target and retention policy.

```java
@Target(value={METHOD,TYPE})
 @Retention(value=RUNTIME)
 @Documented
public @interface Get
```

--------------------------------

### Implement Hello World with Solon

Source: https://solon.noear.org/article/about

Demonstrates three common development patterns in Solon: Handler, Controller (MVC/REST), and Remoting (RPC).

```java
@SolonMain
public class App{
    public static void main(String[] args){
        Solon.start(App.class, args, app->{
            //Handler 模式：
            app.router().get("/hello", (c)->c.output("Hello world!"));
        });
    }
}

//Controller 模式：(mvc or rest-api)
@Controller
public class DemoController{
    //限定 put 方法类型
    @Put
    @Mapping("/mvc/hello")
    public String hello(String name){
        return "Hello " + name;
    }
}

//Remoting 模式：(rpc)
@Mapping("/rpc/hello")
@Remoting
public class HelloServiceImpl implements HelloService{
    @Override
    public String hello(){
        return "Hello world!";
    }
}
```

--------------------------------

### Start Method

Source: https://solon.noear.org/api/org/noear/nami/coder/snack3/integration/solon/NamiSnackPlugin.html

The start method of the NamiSnackPlugin class, used to start the plugin with an AppContext. This is a placeholder for compatibility.

```java
public
void
start(AppContext context)
```

--------------------------------

### Method: start(ConsumerEx<SolonApp> initialize)

Source: https://solon.noear.org/api/org/noear/solon/SimpleSolonApp.html

Simple method to start the application with an initialization consumer.

```java
public SimpleSolonApp start(ConsumerEx<SolonApp> initialize)
throws java.lang.Throwable
```

--------------------------------

### Initialize and Use MCP Client

Source: https://solon.noear.org/article/1126?format=md

Demonstrates building an MCP client and integrating it with a ChatModel for LLM tool binding.

```java
McpClientProvider mcpClient = McpClientProvider.builder()
            .channel(McpChannel.STREAMABLE)
            .apiUrl("http://localhost:8081/mcp")
            .build();

//测试
String resp = mcpClient.callToolAsText("getWeather", Utils.asMap("location", "杭州")).getContent();
System.out.println(resp);


//对接 LLM
ChatModel chatModel = ChatModel.of(apiUrl).provider(...).model(...)
                .defaultToolsAdd(mcpClient) //绑定 mcp 工具
                .build();

ChatResponse resp = chatModel
        .prompt("今天杭州的天气情况？")
        .call();
```

--------------------------------

### Initialize Database

Source: https://solon.noear.org/article/1009

Execute the initialization script using RxSqlUtils.

```java
@Configuration
public class DemoConfig {
    @Bean
    public void init(RxSqlUtils sqlUtils) throws Exception {
        sqlUtils.initDatabase("classpath:demo.sql");
    }
}
```

--------------------------------

### start Method

Source: https://solon.noear.org/api/org/noear/solon/boot/vertx/integration/VxHttpPlugin.html

The start method for the Plugin interface, used to start the application context. It is preserved for compatibility.

```java
public
void
start(AppContext
context)
throws java.lang.Throwable
```

--------------------------------

### Configure and Manage MCP Servers

Source: https://solon.noear.org/article/1353

Demonstrates initializing McpGatewayTalent, adding servers with specific transport parameters and tool-level access controls, and performing runtime management operations.

```java
McpGatewayTalent mcpGateway = new McpGatewayTalent()
        .dynamicThreshold(8)
        .listThreshold(40)
        .searchThreshold(100);

// 方式 1：通过 McpServerParameters 添加
mcpGateway.addMcpServer("weather", new McpServerParameters().then(e->{
            e.setTransport("stdio");
            e.setCommand("npx");
            e.addArgVar("-y");
            e.addArgVar("@modelcontextprotocol/server-weather");
        }));
        
// 方式 1+：接入时做工具级开放控制（只暴露该服务的部分工具）
mcpGateway.addMcpServer("database",new McpServerParameters().then(e-> {
            e.setTransport("stdio");
            e.setCommand("npx");
            e.setArgs(Arrays.asList("-y", "@modelcontextprotocol/server-database"));
            e.setAllowedTools(Arrays.asList("query", "list_tables"));
            e.setDisallowedTools(Arrays.asList("drop_table", "execute_raw"));
        }));

// 方式 2：通过 McpClientProvider 添加
McpClientProvider provider = McpClientProviders.fromMcpServer(params);
mcpGateway.addMcpServer("database", provider);

// 运行时管理
mcpGateway.removeMcpServer("weather");       // 移除并关闭连接
mcpGateway.refreshMcpServer("database");      // 刷新工具列表（权限变更后）
mcpGateway.refreshMcpServerAll();             // 刷新所有 MCP 服务

// 查询
Set<String> serverNames = mcpGateway.getMcpServerNames();
boolean exists = mcpGateway.hasMcpServer("database");
```

--------------------------------

### start Method

Source: https://solon.noear.org/api/org/apache/logging/log4j/solon/integration/Log4j2Plugin.html

The start method of the Log4j2Plugin class, which is part of the Plugin interface. It is intended for starting the application context.

```java
public void start(AppContext context)
throws java.lang.Throwable
```

--------------------------------

### Initialize Web Runtime

Source: https://solon.noear.org/article/1430

Sets up web gateways, controllers, file watchers, and automatically launches the browser interface based on the host operating system.

```java
    private void runWeb(HarnessEngine agentRuntime, AgentSettings settings, CliShell cliShell) {
        //web ws gate
        WebGate webGate = new WebGate(agentRuntime);
        WebSocketRouter.getInstance().of("/web/gate", webGate);

        //web
        BeanWrap webController = Solon.context().wrapAndPut(WebController.class, new WebController(agentRuntime, webGate, loopScheduler));
        Solon.app().router().add(webController);

        WebSettingsController settingsController = new WebSettingsController(agentRuntime, settings);
        BeanWrap webSettingsController = Solon.context().wrapAndPut(WebSettingsController.class, settingsController);
        Solon.app().router().add(webSettingsController);

        BeanWrap webChannel = Solon.context().wrapAndPut(WebChannel.class, new WebChannel(agentRuntime, webGate));
        Solon.app().router().add(webChannel);

        // 启动微信通道
        RunUtil.async((Runnable) webChannel.get());

        // 启动工作区文件变化监听
        try {
            Path workspacePath = Paths.get(agentRuntime.getWorkspace()).toAbsolutePath().normalize();
            WorkspaceWatcher workspaceWatcher = new WorkspaceWatcher(workspacePath);
            workspaceWatcher.addBroadcastHandler(webGate::broadcastRaw);
            workspaceWatcher.start();
        } catch (Exception e) {
            // watcher 启动失败不影响主流程
        }

        if (cliShell == null) {
            return;
        }

        RunUtil.async(() -> {
            try {
                Thread.sleep(500);

                String url = "http://localhost:" + Solon.cfg().serverPort() + "/";

                if (JavaUtil.IS_WINDOWS) {
                    new ProcessBuilder("cmd", "/c", "start", url.replace("&", "^&")).start();
                } else if (JavaUtil.IS_MAC) {
                    new ProcessBuilder("open", url).start();
                } else {
                    new ProcessBuilder("xdg-open", url).start();
                }

                if (cliShell != null) {
                    cliShell.printWelcome("Web interface: " + url);
                }
            } catch (Throwable e) { // 使用 Throwable 捕获更全面
                LOG.warn("Failed to open browser: {}", e.getMessage());
            }
        });
    }
```

--------------------------------

### Method: start

Source: https://solon.noear.org/api/org/noear/solon/scheduling/simple/SimpleScheduler.html

Starts the scheduler.

```java
public
void
start()
           throws java.lang.Throwable
```

--------------------------------

### Apply Wood in Solon Application

Source: https://solon.noear.org/article/330

Demonstrates initializing the application with SQL logging and using @Db for dependency injection of mappers and contexts.

```java
//启动应用
@SolonMain
public class DemoApp {
    public static void main(String[] args) {
        Solon.start(DemoApp.class, args, (app) -> {
            if (Solon.cfg().isDebugMode() || Solon.cfg().isFilesMode()) {
                //执行后打印sql
                WoodConfig.onExecuteAft(cmd -> {
                    System.out.println("[Wood]" + cmd.text + "\r\n" + cmd.paramMap());
                });
            }
        });
    }
}

//应用
@Component
public class AppService{
    @Db
    AppMapper appMapper; //xml sql mapper

    @Db
    BaseMapper<App> appBaseMapper; //base mapper

    @Db
    DbContext db;
    
    public void test(){
        //三种不同接口的样例
        App app1 = appMapper.getAppById(12);
        App app2 = appBaseMapper.getById(12);
        App app3 = db.table("app").whereEq("id",12).selectItem("*", App.class);
        
        //关联+分页查询
        List<User> users = db.table("user u")
          .innerJoin("user_ext e").onEq("u.id","e.user_id")
          .whereEq("u.type",11)
          .limit(100,20)
          .selectList("u.*,e.sex,e.label", User.class);
    }
}
```

--------------------------------

### guid

Source: https://solon.noear.org/api/org/noear/solon/Utils.html

Generate GUID.

```java
public static java.lang.String guid()
```

--------------------------------

### Implement SimpleAgent Hello World

Source: https://solon.noear.org/article/1323

Demonstrates initializing a ChatModel and a SimpleAgent with a custom time-fetching tool.

```java
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.simple.SimpleAgent;
import org.noear.solon.ai.annotation.ToolMapping;
import org.noear.solon.ai.chat.ChatModel;
import org.noear.solon.ai.chat.tool.MethodToolProvider;

import java.time.LocalDateTime;

public class DemoApp {
    public static void main(String[] args) throws Throwable {
        ChatModel chatModel = ChatModel.of("https://api.moark.com/v1/chat/completions")
                .apiKey("***")
                .model("Qwen3-32B")
                .build();

        SimpleAgent robot = SimpleAgent.of(chatModel)
                .defaultToolAdd(new TimeTool())
                .build();

        String answer = robot.prompt( "现在几点了？")
                .call()
                .getContent();

        System.out.println("Robot 答复: " + answer);
    }

    public static class TimeTool extends AbsToolProvider {
        @ToolMapping(description = "获取当前系统时间")
        public String getTime() {
            return LocalDateTime.now().toString();
        }
    }
}
```

--------------------------------

### 创建 Hello World 应用

Source: https://solon.noear.org/article/compare-springcloud

使用 SolonMain 启动一个基础的 REST API 服务。

```java
@SolonMain
public class DemoApp {
    public static void main(String[] args) {
        Solon.start(DemoApp.class, args, app->{
          app.router().get("/", c -> c.output("Hello world!"));
        });
    }
}
```

--------------------------------

### Start Method

Source: https://solon.noear.org/api/org/noear/nami/channel/socketd/integration/solon/NamiSocketdPlugin.html

The start method of the NamiSocketdPlugin class, which is part of the Plugin interface. It is used for starting the plugin and is currently reserved for compatibility.

```java
public
void start(AppContext context)
```

--------------------------------

### Knife4jPlugin start Method

Source: https://solon.noear.org/api/com/github/xiaoymin/knife4j/solon/integration/Knife4jPlugin.html

The start method of the Knife4jPlugin class, which is part of the Plugin interface. It is used for starting the plugin with an application context.

```java
public
void
start(AppContext context)
throws java.lang.Throwable
```

--------------------------------

### 启动初始化接口加载配置

Source: https://solon.noear.org/article/301?format=md

在 Solon.start 启动回调中动态加载配置文件或环境变量。

```java
Solon.start(App.class, args, app->{
    app.cfg().loadAdd("demo.yml");
});
```

```java
Solon.start(App.class, args, app->{
    //通过前缀加载环境变量
    app.cfg().loadEnv("demo.");
});
```

--------------------------------

### Create Controller and Template

Source: https://solon.noear.org/article/105

Example of a controller returning a ModelAndView and the corresponding Beetl template file.

```java
//顺便，加个国际化在模板里的演法
@I18n
@Controller
public class DemoController{
    @Mapping("/test")
    public ModelAndView test() {
        ModelAndView model = new ModelAndView("beetl.htm");
        model.put("title", "dock");
        model.put("msg", "你好 world!");

        return model;
    }
}
```

```html
<!DOCTYPE html>
<html>
<head>
    <title>${title}</title>
</head>
<body>
beetl::${msg}；i18n::${@i18n.get("login.title")}
</body>
</html>
```

--------------------------------

### Method Details: get

Source: https://solon.noear.org/api/org/noear/solon/scheduling/retry/RetryableTask.html

Gets the answer.

```java
public T get()
Returns:
    the value returned by the executed method
```

--------------------------------

### Create smart-doc.json configuration

Source: https://solon.noear.org/article/169

Define the framework as 'solon' and specify the output path in the smart-doc.json file.

```json
{
  "framework": "solon",
  "outPath": "src/main/resources/static/doc"
}
```

--------------------------------

### Start Method

Source: https://solon.noear.org/api/org/noear/nami/coder/hessian/integration/solon/NamiHessianPlugin.html

The start method of the NamiHessianPlugin class.

```java
public	void	start(AppContext	context)
启动（保留，为兼容性过度）
```

--------------------------------

### 应用初始化函数时机点

Source: https://solon.noear.org/article/240

在 Solon.start 方法中通过回调函数执行应用初始化逻辑。

```java
import org.noear.solon.Solon;
import org.noear.solon.annotation.SolonMain;

@SolonMain
public class App{
    public static void main(String[] args){
        Solon.start(App.class, args, (app)->{
            //应用初始化时机点
        });
    } 
}
```

--------------------------------

### Flow Execution Setup

Source: https://solon.noear.org/article/983

How to assemble a component container, configure the driver, and execute a workflow graph.

```APIDOC
## Flow Execution

### Description
Assemble components into a container, initialize the FlowEngine with a driver, and execute a defined graph.

### Usage
```java
// Build component container
MapContainer container = new MapContainer();
container.putComponent("DemoCom", (ctx, node)->{
    System.out.println(node.getId());
});

// Build driver and engine
SimpleFlowDriver flowDriver = new SimpleFlowDriver(container);
FlowEngine engine = FlowEngine.newInstance(flowDriver);

// Define and execute graph
Graph graph = Graph.create("c1", decl -> {
    decl.addActivity("n1").task("@DemoCom");
});

engine.eval(graph, "n1", FlowContext.of());
```
```

--------------------------------

### 获取 SolonApp 实例

Source: https://solon.noear.org/article/420

展示如何通过 Solon.start() 初始化应用并获取 SolonApp 实例，以及如何通过全局方法访问。

```java
import org.noear.solon.Solon;
import org.noear.solon.SolonApp;
import org.noear.solon.annotation.SolonMain;

@SolonMain
public class DemoApp{
    public static void main(String[] args){
        //可以在 start() 返回得到它
        SolonApp app = Solon.start(DemoApp.class, args, app->{
          //或者，可以通初始化函数获得它
        });
    }
}

//最重要的是：start() 后，通过全局实例得到它（为手动开发提供便利）：
Solon.app();
```

--------------------------------

### get Method

Source: https://solon.noear.org/api/org/noear/solon/i18n/impl/I18nBundleLocal.html

Detailed information for the get method.

```java
public
java.lang.String
get(java.lang.String
key)
```

--------------------------------

### Initialize and Configure OpenApiGatewayTalent

Source: https://solon.noear.org/article/1353

Demonstrates how to initialize the OpenApiGatewayTalent, add API sources, and build a ReAct agent with the talent.

```java
// 1. 初始化 Talent
OpenApiGatewayTalent apiTalent = new OpenApiGatewayTalent()
        .dynamicThreshold(5)      // 超过 5 个接口开启摘要模式
        .listThreshold(30)        // 超过 30 个接口开启名字列表模式
        .searchThreshold(100)     // 超过 100 个接口开启强制搜索模式
        .maxContextLength(10000)  // 结果截断长度
        .defaultTimeout(Duration.ofSeconds(30))
        .defaultAuthenticator((http, tool) -> {
             http.header("Authorization", "Bearer your-token"); // 全局认证
        });

// 2. 挂载多个业务模块的 API（支持 http 或 classpath）
apiTalent.addApi("http://order-service:8081/v3/api-docs", "http://order-service:8081");
apiTalent.addApi("classpath:swagger/user-api.json", "http://user-service:8082");

// 2.1 也可使用 ApiSource 对象精细配置（支持独立认证、权限过滤、超时等）
ApiSource source = new ApiSource();
source.setDocUrl("http://pay-service:8083/v3/api-docs");
source.setApiBaseUrl("http://pay-service:8083");
source.setAllowedTools(Arrays.asList("createPayment", "queryPayment")); // 仅加载 2 个接口
source.setAuthenticator(ApiAuthenticator.bearer("pay-service-token"));
source.setTimeout(Duration.ofSeconds(60));
apiTalent.addApi(source);

// 3. 构建智能体
ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
        .role("高级业务助理")
        .instruction("请优先使用提供的业务 API 解决问题，不要猜测接口参数。")
        .defaultTalentAdd(apiTalent)
        .build();

// 4. 运行时动态管理
apiTalent.removeApi("http://order-service:8081/v3/api-docs");  // 移除某个源
apiTalent.refreshApi("http://pay-service:8083/v3/api-docs");   // 刷新权限过滤
apiTalent.refreshApiAll();                                      // 刷新所有源
```

--------------------------------

### Method Details - get

Source: https://solon.noear.org/api/org/noear/solon/health/detector/DetectorManager.html

Details for the get method.

```java
public static Detector get(java.lang.String name)
```

--------------------------------

### SessionstateRedissonPlugin start method

Source: https://solon.noear.org/api/org/noear/solon/sessionstate/redisson/integration/SessionstateRedissonPlugin.html

Starts the plugin, intended for compatibility.

```java
public void start(AppContext context)

```

--------------------------------

### Implement Web Application

Source: https://solon.noear.org/article/1135

Basic setup for a Solon web application using the smart-http server.

```java
public class DemoApp {
    public static void main(String[] args) {
        Solon.start(DemoApp.class, args, app->{
            //开始调试模式
            //app.onEvent(HttpServerConfigure.class, e->{
            //    e.enableDebug(Solon.cfg().isDebugMode());
            //});
        });
    }
}

@Controller
public class DemoController{
    @Mapping("/hello")
    public String hello(){
        return "Hello world!";
    }
}
```

--------------------------------

### Manual MCP Server Endpoint Configuration

Source: https://solon.noear.org/article/998?format=md

Demonstrates how to manually define a tool provider and configure an McpServerEndpointProvider to start an MCP server.

```APIDOC
## Manual MCP Server Configuration

### Description
Use `McpServerEndpointProvider` to manually build and start an MCP server endpoint. Tools are registered via `MethodToolProvider`.

### Usage
```java
// Define a tool
public class McpServerTool {
    @ToolMapping(description = "查询天气预报")
    public String getWeather(@Param(description = "城市位置") String location) {
        return "晴，14度";
    }
}

// Configure and start
McpServerEndpointProvider serverEndpoint = McpServerEndpointProvider.builder()
        .name("mcp-case4")
        .channel(McpChannel.STDIO)
        .build();

serverEndpoint.addTool(new MethodToolProvider(new McpServerTool()));
serverEndpoint.postStart();
```
```

--------------------------------

### HarnessEngine.of

Source: https://solon.noear.org/article/1468?format=md

Initializes the HarnessEngine with a workspace and harness home directory.

```APIDOC
## HarnessEngine.of(workspace, harnessHome)

### Description
Initializes the engine instance defining the workspace root and the harness home directory for persistent data.

### Parameters
- **workspace** (String) - Required - The current working directory for file operations and command execution.
- **harnessHome** (String) - Required - The directory where runtime data (sessions, skills, agents, etc.) is stored.
```

--------------------------------

### Initialize Web Interface and Watcher

Source: https://solon.noear.org/article/1430?format=md

Sets up web routing, workspace file monitoring, and automatically launches the browser interface.

```java
private void runWeb(HarnessEngine agentRuntime, AgentSettings settings, CliShell cliShell) {
        //web ws gate
        WebGate webGate = new WebGate(agentRuntime);
        WebSocketRouter.getInstance().of("/web/gate", webGate);

        //web
        BeanWrap webController = Solon.context().wrapAndPut(WebController.class, new WebController(agentRuntime, webGate, loopScheduler));
        Solon.app().router().add(webController);

        WebSettingsController settingsController = new WebSettingsController(agentRuntime, settings);
        BeanWrap webSettingsController = Solon.context().wrapAndPut(WebSettingsController.class, settingsController);
        Solon.app().router().add(webSettingsController);

        BeanWrap webChannel = Solon.context().wrapAndPut(WebChannel.class, new WebChannel(agentRuntime, webGate));
        Solon.app().router().add(webChannel);

        // 启动微信通道
        RunUtil.async((Runnable) webChannel.get());

        // 启动工作区文件变化监听
        try {
            Path workspacePath = Paths.get(agentRuntime.getWorkspace()).toAbsolutePath().normalize();
            WorkspaceWatcher workspaceWatcher = new WorkspaceWatcher(workspacePath);
            workspaceWatcher.addBroadcastHandler(webGate::broadcastRaw);
            workspaceWatcher.start();
        } catch (Exception e) {
            // watcher 启动失败不影响主流程
        }

        if (cliShell == null) {
            return;
        }

        RunUtil.async(() -> {
            try {
                Thread.sleep(500);

                String url = "http://localhost:" + Solon.cfg().serverPort() + "/";

                if (JavaUtil.IS_WINDOWS) {
                    new ProcessBuilder("cmd", "/c", "start", url.replace("&", "^&")).start();
                } else if (JavaUtil.IS_MAC) {
                    new ProcessBuilder("open", url).start();
                } else {
                    new ProcessBuilder("xdg-open", url).start();
                }

                if (cliShell != null) {
                    cliShell.printWelcome("Web interface: " + url);
                }
            } catch (Throwable e) { // 使用 Throwable 捕获更全面
                LOG.warn("Failed to open browser: {}", e.getMessage());
            }
        });
    }
```

--------------------------------

### Method Details - start

Source: https://solon.noear.org/api/org/noear/solon/health/detector/DetectorManager.html

Details for the start method.

```java
public static void start(java.lang.String... names)
                  throws java.lang.Throwable
```

--------------------------------

### SqlUtilsPlugin start method

Source: https://solon.noear.org/api/org/noear/solon/data/sql/integration/SqlUtilsPlugin.html

Starts the plugin (reserved for compatibility).

```java
public void start(AppContext context) throws java.lang.Throwable
```

--------------------------------

### Define YAML Configuration Files

Source: https://solon.noear.org/article/274?format=md

Examples of YAML configuration structures for default and manual loading.

```yml
server.port: 8080

solon.app:
  group: "demo"
  name: "demoapp"
```

```yml
user.name: "noear"
user.level: 0
```

--------------------------------

### substring Method (start)

Source: https://solon.noear.org/api/org/noear/solon/data/rx/sql/SqlBuilder.html

Extracts a substring from the start index.

```java
public
java.lang.String substring(int start)
```

--------------------------------

### Method Details: get

Source: https://solon.noear.org/api/org/noear/solon/logging/AppenderManager.html

Details of the get method.

```java
public static AppenderHolder get(java.lang.String name)
```

--------------------------------

### Unsupported Setter Injection in Solon

Source: https://solon.noear.org/article/compare-springboot

Example of a setter injection pattern that is not supported by the Solon framework.

```java
@Component
public class DemoCom {
    private B b;
    
    public void setB(@Inject B b){
        this.b = b;
    }
}
```

--------------------------------

### Check Async Started

Source: https://solon.noear.org/api/org/noear/solon/net/socketd/handle/SocketdContext.html

Checks if an asynchronous operation has started.

```java
public boolean asyncStarted(){
    // Overridden in ContextEmpty
}
```

--------------------------------

### 在 main 方法中顺序执行代码

Source: https://solon.noear.org/article/779?format=md

在 Solon.start 之后直接编写代码，代码会按顺序执行。

```java
import org.noear.solon.Solon;

public class DemoApp {
    public static void main(String[] args) {
        Solon.start(DemoApp.class, args);
        
        //执行代码
    }
}
```

--------------------------------

### Properties Configuration Example

Source: https://solon.noear.org/api/org/noear/solon/sessionstate/redisson/RedissonBuilder.html

Example configuration properties for Redisson.

```properties
test.cache1:
  server: "localhost:6379"
  db: 0 #默认为 0，可不配置
  password: ""
  maxTotal: 200 #默认为 200，可不配
  ...
```

--------------------------------

### LoadBalance Wrap Example

Source: https://solon.noear.org/api/org/noear/solon/core/LoadBalance.html

Example usage of LoadBalance.LoadBalanceWrap.

```java
LoadBalance.LoadBalanceWrap
```

--------------------------------

### 在应用启动时注册拦截器

Source: https://solon.noear.org/article/226

在 Solon.start 的回调函数中（时机点5）注册 Bean 拦截器。

```java
public class DemoApp{
    public void static main(String[] args){
        Solon.start(DemoApp.clas, args, app->{
            //...时机点5
            app.context().beanInterceptorAdd(DemoAop.class, new DemoInterceptor());
        });
    }
}
```

--------------------------------

### JSONException Example

Source: https://solon.noear.org/api/org/noear/solon/configurationprocessor/json/JSONException.html

Example of how to wrap JSONException in a RuntimeException.

```java
public JSONArray toJSONObject() {
    try {
        JSONObject result = new JSONObject();
        ...
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }
}
```

--------------------------------

### values() Method Example

Source: https://solon.noear.org/api/org/noear/solon/aot/hint/ExecutableMode.html

Example of how to iterate over the ExecutableMode constants.

```java
for (ExecutableMode c : ExecutableMode.values())
    System.out.println(c);
```

--------------------------------

### 使用 solon.docs 配置自动构建

Source: https://solon.noear.org/article/797?format=md

通过 YAML 配置实现文档的自动发现与聚合，支持设置 uriPattern、contextPathPattern 和 basicAuth。

```yml
solon.docs:
  discover:
    enabled: true
    uriPattern: "swagger/v2?group={service}"  #目标服务的文档接口路径模式（要么带变量 {service}，要么用统一固定值）
    contextPathPattern: "/{service}" #可选 #文档资源组的上下文路径（在拼接调试地址地用）
    syncStatus: false  #同步目标服务上下线状态（如果下线，则文档不显示）
    basicAuth:           #可选
      admin: 1234      
    excludedServices:  #排除目标服务名
      - "xx"
  routes:
     - DocDocket
     - DocDocket
```

--------------------------------

### EventListener Demo

Source: https://solon.noear.org/api/org/noear/solon/core/event/package-summary.html

Examples of how to use the EventListener interface.

```java
EventListener<Event> |  事件监听者 //demo1: 在手动添加Listener Solon.app().onEvent(Throwable.class, (err)->{ }); //demo2: 自动添加Listener  
```

--------------------------------

### GET Request

Source: https://solon.noear.org/api/org/noear/solon/net/http/HttpUtils.html

Performs a GET request and returns the response body.

```java
java.lang.String get()
              throws HttpException
```

--------------------------------

### Manual Configuration and Bean Management in Solon

Source: https://solon.noear.org/article/features

Demonstrates manual retrieval of configurations, bean injection, routing, and RPC service handling without relying solely on annotations.

```java
//手动获取配置（Props 为 Properties 增强版）
Props db = Solon.cfg().getProp("db");

//手动获取容器里的Bean
UserService userService = Solon.context().getBean(UserService.class);

//手动监听http post请求
Solon.app().router().post("/user/update", x-> userService.updateById(x.paramMap()));

//手动添加个RPC服务
Solon.app().router().add("/rpc/", HelloServiceImpl.class, true);

//手动获取一个RPC服务消费端
HelloService helloService = Nami.builder().create(HelloService.class);

//手动为容器添加组件
Solon.context().wrapAndPut(DemoService.class);
```

--------------------------------

### Method Details: get

Source: https://solon.noear.org/api/org/noear/solon/i18n/I18nService.html

Detailed information for the get method.

```java
public
java.lang.String
get(java.util.Locale
locale,
java.lang.String
key)
```
Tokens:
Raw