---
name: solon-pitfalls
description: Solon框架的正确API用法（redisx/定时任务/HTTP/注解/配置文件/打包），踩坑后实测确认
metadata:
  type: reference
---

联调实测确认的 Solon 4.0.4 正确用法（多次踩坑后验证，务必牢记）：

- **配置文件名**：Solon 默认读 `app.yml`，**不是** `application.yml`。配置文件名错会导致所有配置读不到（null）。
- **YAML 插件**：默认只读 .properties，需加 `org.noear:solon-config-yaml` 依赖才能读 .yml，否则报 `profile is not supported`。
- **打包插件**：用 `org.noear:solon-maven-plugin`（repackage 目标），**不要用** maven-assembly-plugin（版本号易错，且非 Solon 标配）。插件版本用 3.10.5（与 solon 主框架 4.0.4 不同版本线）。
- **日志**：需加 `slf4j-simple` 实现，否则 SLF4J 退化为 NOP 无日志。
- **Redis（redisx）**：是独立库，无自动注入。手动 `new RedisClient(Properties)`，Properties key 为 `server`/`db`/`password`/`user`/`maxTotal`。**不要**用 `@Inject("${redis}") RedisClient`。API：`getBucket().store/get`、`open(session -> session.key(k).delete())`。
- **定时任务注解**：`@Scheduled`/`@EnableScheduling` 在 `org.noear.solon.scheduling.annotation`（来自 `solon-scheduling` 依赖，非 `solon-scheduling-simple`）。
- **Context**：路径 `org.noear.solon.core.handle.Context`（非 `org.noear.solon.core.Context`）。方法：`path()`、`queryString()`、`method()`、`body()`、`headerNames()`、`header(name)`、`status(int)`、`headerSet(k,v)`、`output(String)`。
- **HTTP 客户端**：`solon-net-httputils`。`HttpUtils.http(url).exec(method)` 返回 HttpResponse。状态码 `resp.code()`（非 status）。body 用 `bodyOfJson(String)`（无 `body(String)` 单参重载，只有 `body(byte[])`/`body(content,contentType)`）。响应体 `resp.bodyAsString()`。
- **占位符**：`${KEY}` 能解析 `System.setProperty` 注入的值（联调验证）。
- **JSON 返回**：Controller 返回 HashMap 会被 snack4 序列化为 `{key=value}` 非标准 JSON。返回标准 JSON 用 snack4 ONode（`new ONode().asObject()` + `.set(k,v)`）+ `@Produces("application/json")`。**不使用 fastjson**（规避 0day 漏洞），JSON 处理统一用 Solon 内置 snack4（`org.noear.snack4.ONode`）。
- **snack4 API**：解析 `ONode.ofJson(str)`；取值 `node.getOrNull(key).getString()`/`.getLong()`；构造对象 `new ONode().asObject().set(k,v)`；序列化 `ONode.serialize(obj)` 或 `node.toJson()`。

关联 [[architecture-local-passthrough]]、[[jeecg-token-mechanism]]。