tinystruct-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tinystruct Development Patterns

tinystruct 开发模式

Architecture and implementation patterns for building modules with the tinystruct Java framework – a lightweight system where CLI and HTTP are equal citizens.

使用tinystruct Java框架构建模块的架构与实现模式——这是一个将CLI和HTTP视为同等重要组件的轻量级系统。

When to Use

适用场景

Creating new
```
Application
```
modules by extending
```
AbstractApplication
```
.
Defining routes and command-line actions using
```
@Action
```
.
Handling per-request state via
```
Context
```
.
Performing JSON serialization using the native
```
Builder
```
component.
Configuring database connections or system settings in
```
application.properties
```
.
Generating or re-generating the standard
```
bin/dispatcher
```
entry point via
```
ApplicationManager.init()
```
.
Debugging routing conflicts (Actions) or CLI argument parsing.

通过继承
```
AbstractApplication
```
创建新的
```
Application
```
模块。
使用
```
@Action
```
定义路由和命令行操作。
通过
```
Context
```
处理每个请求的状态。
使用原生
```
Builder
```
组件执行JSON序列化。
在
```
application.properties
```
中配置数据库连接或系统设置。
通过
```
ApplicationManager.init()
```
生成或重新生成标准的
```
bin/dispatcher
```
入口点。
调试路由冲突（Actions）或CLI参数解析问题。

How It Works

工作原理

The tinystruct framework treats any method annotated with

@Action

as a routable endpoint for both terminal and web environments. Applications are created by extending

AbstractApplication

, which provides core lifecycle hooks like

init()

and access to the request

Context

Routing is handled by the

ActionRegistry

, which automatically maps path segments to method arguments and injects dependencies. For data-only services, the native

Builder

component should be used for JSON serialization to maintain a zero-dependency footprint. The framework also includes a utility in

ApplicationManager

to bootstrap the project's execution environment by generating the

bin/dispatcher

script.

tinystruct框架会将所有带有

@Action

注解的方法视为终端和Web环境均可访问的路由端点。应用通过继承

AbstractApplication

创建，该类提供了

init()

等核心生命周期钩子，以及对请求

Context

的访问权限。

路由由

ActionRegistry

处理，它会自动将路径段映射到方法参数并注入依赖项。对于仅处理数据的服务，应使用原生

Builder

组件进行JSON序列化，以保持零依赖的特性。框架还包含

ApplicationManager

中的工具，可通过生成

bin/dispatcher

脚本来引导项目的执行环境。

Examples

示例

Basic Application (MyService)

基础应用（MyService）

java

public class MyService extends AbstractApplication {
    @Override
    public void init() {
        this.setTemplateRequired(false); // Disable .view lookup for data/API apps
    }

    @Override public String version() { return "1.0.0"; }

    @Action("greet")
    public String greet() {
        return "Hello from tinystruct!";
    }
}

java

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!";
    }
}

Parameterized Routing (getUser)

参数化路由（getUser）

java

// Handles /api/user/123 (Web) or "bin/dispatcher api/user/123" (CLI)
@Action("api/user/(\\d+)")
public String getUser(int userId) {
    return "User ID: " + userId;
}

java

// 处理/api/user/123（Web）或"bin/dispatcher api/user/123"（CLI）
@Action("api/user/(\\d+)")
public String getUser(int userId) {
    return "User ID: " + userId;
}

HTTP Mode Disambiguation (login)

HTTP模式区分（login）

java

@Action(value = "login", mode = Mode.HTTP_POST)
public boolean doLogin() {
    // Process login logic
    return true;
}

java

@Action(value = "login", mode = Mode.HTTP_POST)
public boolean doLogin() {
    // 处理登录逻辑
    return true;
}

Native JSON Data Handling (getData)

原生JSON数据处理（getData）

java

@Action("api/data")
public Builder getData() throws ApplicationException {
    Builder builder = new Builder();
    builder.put("status", "success");
    Builder nested = new Builder();
    nested.put("id", 1);
    nested.put("name", "James");
    builder.put("data", nested);
    return builder;
}

java

@Action("api/data")
public Builder getData() throws ApplicationException {
    Builder builder = new Builder();
    builder.put("status", "success");
    Builder nested = new Builder();
    nested.put("id", 1);
    nested.put("name", "James");
    builder.put("data", nested);
    return builder;
}

Configuration

配置

Settings are managed in

src/main/resources/application.properties

properties

undefined

设置在

src/main/resources/application.properties

中管理。

properties

undefined

Database

driver=org.h2.Driver database.url=jdbc:h2:~/mydb

App specific

my.service.endpoint=https://api.example.com

undefined

my.service.endpoint=https://api.example.com

undefined

Testing Patterns

测试模式

Use JUnit 5 to test actions by verifying they are registered in the

ActionRegistry

java

@Test
void testActionRegistration() {
    Application app = new MyService();
    app.init();
    
    ActionRegistry registry = ActionRegistry.getInstance();
    assertNotNull(registry.get("greet"));
}

使用JUnit 5测试操作，验证它们是否已在

ActionRegistry

中注册。

java

@Test
void testActionRegistration() {
    Application app = new MyService();
    app.init();
    
    ActionRegistry registry = ActionRegistry.getInstance();
    assertNotNull(registry.get("greet"));
}

Red Flags & Anti-patterns

警示信号与反模式

Symptom	Correct Pattern
Importing `com.google.gson` or `com.fasterxml.jackson`	Use `org.tinystruct.data.component.Builder` .
`FileNotFoundException` for `.view` files	Call `setTemplateRequired(false)` in `init()` for API-only apps.
Annotating `private` methods with `@Action`	Actions must be `public` to be registered by the framework.
Hardcoding `main(String[] args)` in apps	Use `bin/dispatcher` as the entry point for all modules.
Manual `ActionRegistry` registration	Prefer the `@Action` annotation for automatic discovery.

症状	正确模式
导入 `com.google.gson` 或 `com.fasterxml.jackson`	使用 `org.tinystruct.data.component.Builder` 。
出现 `.view` 文件的 `FileNotFoundException`	在仅API应用的 `init()` 中调用 `setTemplateRequired(false)` 。
为 `private` 方法添加 `@Action` 注解	操作必须是 `public` 才能被框架注册。
在应用中硬编码 `main(String[] args)`	将 `bin/dispatcher` 作为所有模块的入口点。
手动注册 `ActionRegistry`	优先使用 `@Action` 注解实现自动发现。

Technical Reference

技术参考

Detailed guides are available in the

references/

directory:

Architecture & Config — Abstractions, Package Map, Properties
Routing & @Action — Annotation details, Modes, Parameters
Data Handling — Using the native
```
Builder
```
for JSON
System & Usage — Context, Sessions, Events, CLI usage
Testing Patterns — JUnit 5 integration and ActionRegistry testing

详细指南可在

references/

目录中找到：

Architecture & Config — 抽象概念、包映射、属性配置
Routing & @Action — 注解详情、模式、参数
Data Handling — 使用原生
```
Builder
```
处理JSON
System & Usage — 上下文、会话、事件、CLI使用
Testing Patterns — JUnit 5集成与ActionRegistry测试

Reference Source Files (Internal)

参考源文件（内部）

src/main/java/org/tinystruct/AbstractApplication.java

— Core base class

src/main/java/org/tinystruct/system/annotation/Action.java

— Annotation & Modes

src/main/java/org/tinystruct/application/ActionRegistry.java

— Routing Engine

src/main/java/org/tinystruct/data/component/Builder.java

— JSON/Data Serializer

src/main/java/org/tinystruct/AbstractApplication.java

— 核心基类

src/main/java/org/tinystruct/system/annotation/Action.java

— 注解与模式

src/main/java/org/tinystruct/application/ActionRegistry.java

— 路由引擎

src/main/java/org/tinystruct/data/component/Builder.java

— JSON/数据序列化器