---
id: gh-tinystruct-patterns
name: "tinystruct-patterns"
url: https://skills.yangsir.net/skill/gh-tinystruct-patterns
author: affaan-m
domain: ai-software-architecture-engineering
tags: ["java", "framework", "design-patterns", "microservices", "backend-development"]
install_count: 2300
rating: 4.30 (120 reviews)
github: https://github.com/affaan-m/everything-claude-code/tree/main/docs/ja-JP/skills/tinystruct-patterns
---

# tinystruct-patterns

> 此技能提供 tinystruct Java 框架的开发模式和最佳实践，涵盖路由、上下文管理、JSON 处理、CLI/HTTP 双模式等。它帮助开发者高效构建可维护的应用模块和微服务，确保代码结构清晰、符合规范，并避免常见反模式，从而提升开发效率和系统稳定性。

**Stats**: 2,300 installs · 4.3/5 (120 reviews)

## Before / After 对比

### 优化 tinystruct 应用的 JSON 数据处理

**Before**:

在没有此技能之前，开发者在 tinystruct 应用中处理 JSON 数据时，常需手动引入并配置第三方库（如 Gson 或 Jackson），这不仅增加了项目依赖，还可能导致集成复杂性，耗费大量时间在库的选型、配置和调试上，影响开发效率和代码一致性。

**After**:

采用该 Skill 推荐的 tinystruct 原生 Builder 组件处理 JSON 数据后，开发者无需引入额外依赖，即可实现高效、统一的数据序列化和反序列化。此技能显著简化了 JSON 处理流程，减少了配置和调试时间，确保了代码的简洁性和框架内的一致性，从而大幅提升了开发效率。

| Metric | Before | After | Change |
|---|---|---|---|
| JSON 处理开发时间 | 60分钟 | 10分钟 | -83% |

## Readme

# tinystruct 開発パターン

**tinystruct** Java フレームワークを使用してモジュールをビルドするためのアーキテクチャと実装パターン。CLIとHTTPが等しく扱われる軽量なシステムです。

## 使用するタイミング

- `AbstractApplication` を拡張して新しい `Application` モジュールを作成するとき。
- `@Action` を使用してルートとコマンドラインアクションを定義するとき。
- `Context` を通じてリクエストごとの状態を処理するとき。
- ネイティブの `Builder` コンポーネントを使用してJSONシリアライゼーションを行うとき。
- `application.properties` でデータベース接続またはシステム設定を構成するとき。
- `ApplicationManager.init()` を通じて標準的な `bin/dispatcher` エントリポイントを生成または再生成するとき。
- ルーティング競合（Action）またはCLI引数解析のデバッグを行うとき。

## 動作の仕組み

tinystruct フレームワークは、`@Action` でアノテーションされたメソッドをターミナルとWeb環境の両方でルーティング可能なエンドポイントとして扱います。アプリケーションは `AbstractApplication` を拡張することで作成され、`init()` などのコアライフサイクルフックとリクエスト `Context` へのアクセスが提供されます。

ルーティングは `ActionRegistry` によって処理され、パスセグメントをメソッド引数に自動的にマッピングして依存関係を注入します。データのみのサービスでは、ゼロ依存のフットプリントを維持するために、JSONシリアライゼーションにネイティブの `Builder` コンポーネントを使用すべきです。フレームワークには `ApplicationManager` のユーティリティも含まれており、`bin/dispatcher` スクリプトを生成することでプロジェクトの実行環境をブートストラップします。

## 例

### 基本アプリケーション（MyService）
```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!";
    }
}
```

### パラメータ付きルーティング（getUser）
```java
// Web: /api/user/123 または CLI: "bin/dispatcher api/user/123" を処理
@Action("api/user/(\\d+)")
public String getUser(int userId) {
    return "User ID: " + userId;
}
```

### HTTPモード分岐（login）
```java
@Action(value = "login", mode = Mode.HTTP_POST)
public boolean doLogin() {
    // ログイン処理
    return true;
}
```

### ネイティブ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;
}
```

## 設定

設定は `src/main/resources/application.properties` で管理されます。

## テストパターン

JUnit 5 を使用して、アクションが `ActionRegistry` に登録されていることを検証することでアクションをテストします。

## レッドフラグとアンチパターン

| 症状 | 正しいパターン |
|---|---|
| `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` アノテーションを優先する。 |

## テクニカルリファレンス

詳細なガイドは `references/` ディレクトリにあります：

- [アーキテクチャと設定](references/architecture.md) — 抽象化、パッケージマップ、プロパティ
- [ルーティングと@Action](references/routing.md) — アノテーションの詳細、モード、パラメータ
- [データ処理](references/data-handling.md) — JSONのためのネイティブ `Builder` の使用
- [システムと使用方法](references/system-usage.md) — Context、セッション、イベント、CLI使用方法
- [テストパターン](references/testing.md) — JUnit 5 統合と ActionRegistry テスト


---
*Source: https://skills.yangsir.net/skill/gh-tinystruct-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-tinystruct-patterns/markdown*