
关于
使用 tinystruct Java 框架开发的专家指导。适用于 tinystruct 代码库或基于 tinystruct 构建的项目——包括创建 Application 类、@Action 映射路由、单元测试、ActionRegistry、HTTP/CLI 双模式处理等。
name: tinystruct-patterns description: tinystruct Java 框架的专家开发指导。在使用 tinystruct 代码库或基于 tinystruct 构建的任何项目时使用 — 包括创建 Application 类、@Action 映射路由、单元测试、ActionRegistry、HTTP/CLI 双模式处理、内置 HTTP 服务器、事件系统、Builder/Builders JSON、AbstractData 数据库持久化、POJO 生成、Server-Sent Events (SSE)、文件上传和出站 HTTP 网络。 origin: ECC
tinystruct 开发模式
使用 tinystruct Java 框架构建模块的架构和实现模式 — 一个轻量级、高性能的框架,将 CLI 和 HTTP 视为平等公民,不需要 main() 方法且配置最少。
核心原则
CLI 和 HTTP 是平等公民。 每个用 @Action 注解的方法理想情况下应该能从终端和 Web 浏览器运行而无需修改。这种"双模式"能力是 tinystruct 的核心设计哲学。
何时激活
何时使用
- 通过继承
AbstractApplication创建新的Application模块。 - 使用
@Action定义路由和命令行操作。 - 通过
Context处理每请求状态。 - 使用原生
Builder和Builders组件进行 JSON 序列化。 - 通过
AbstractDataPOJO 进行数据库持久化。 - 使用
generate命令从数据库表生成 POJO。 - 实现 Server-Sent Events (SSE) 用于实时推送。
- 通过 multipart 数据处理文件上传。
- 使用
URLRequest和HTTPHandler发起出站 HTTP 请求。 - 在
application.properties中配置数据库连接或系统设置。 - 调试路由冲突(Actions)或 CLI 参数解析。
工作原理
tinystruct 框架将任何用 @Action 注解的方法视为终端和 Web 环境的可路由端点。应用通过继承 AbstractApplication 创建,它提供核心生命周期钩子如 init() 和对请求 Context 的访问。
路由由 ActionRegistry 处理,它自动将路径段映射到方法参数并注入依赖。对于纯数据服务,应使用原生 Builder 和 Builders 组件进行 JSON 序列化以保持零依赖。数据库层使用 AbstractData POJO 配合 XML 映射文件进行 CRUD 操作,无需外部 ORM 库。
示例
基础应用 (MyService)
public class MyService extends AbstractApplication {
@Override
public void init() {
this.setTemplateRequired(false); // 对数据/API 应用禁用 .view 查找
}
@Override public String version() { return "1.0.0"; }
@Action("greet")
public String greet() {
return "Hello from tinystruct!";
}
// 路径参数: GET /?q=greet/James 或 bin/dispatcher greet/James
@Action("greet")
public String greet(String name) {
return "Hello, " + name + "!";
}
}
HTTP 模式区分 (login)
@Action(value = "login", mode = Mode.HTTP_POST)
public String doLogin(Request<?, ?> request) throws ApplicationException {
request.getSession().setAttribute("userId", "42");
return "Logged in";
}
原生 JSON 数据处理 (Builder + Builders)
import org.tinystruct.data.component.Builder;
import org.tinystruct.data.component.Builders;
@Action("api/data")
public String getData() throws ApplicationException {
Builders dataList = new Builders();
Builder item = new Builder();
item.put("id", 1);
item.put("name", "James");
dataList.add(item);
Builder response = new Builder();
response.put("status", "success");
response.put("data", dataList);
return response.toString(); // {"status":"success","data":[{"id":1,"name":"James"}]}
}
SSE (Server-Sent Events)
import org.tinystruct.http.SSEPushManager;
@Action("sse/connect")
public String connect() {
return "{\"type\":\"connect\",\"message\":\"Connected to SSE\"}";
}
// 推送到特定客户端
String sessionId = getContext().getId();
Builder msg = new Builder();
msg.put("text", "Hello, user!");
SSEPushManager.getInstance().push(sessionId, msg);
// 广播到所有
SSEPushManager.getInstance().broadcast(msg);
文件上传
import org.tinystruct.data.FileEntity;
@Action(value = "upload", mode = Mode.HTTP_POST)
public String upload(Request<?, ?> request) throws ApplicationException {
List<FileEntity> files = request.getAttachments();
if (files != null) {
for (FileEntity file : files) {
System.out.println("Uploaded: " + file.getFilename());
}
}
return "Upload OK";
}
配置
设置在 src/main/resources/application.properties 中管理。
# 数据库
driver=org.h2.Driver
database.url=jdbc:h2:~
兼容工具
Claude CodeCursor
标签
后端开发

