tinystruct framework Documentation

English | 中文

Welcome to the tinystruct framework documentation. This documentation provides comprehensive guidance for using and developing with the tinystruct framework.

欢迎查阅 tinystruct 框架文档。本文档为使用和开发 tinystruct 框架提供全面的指导。

What's New in v1.7.29

• Asymmetric RSA & Configurable JWT Security: RSA public/private key pairs and flexible configuration via application.properties
• Advanced HTTP Server Security: Host header filtering (server.name), path traversal prevention, and secure cookies
• Decoupled Architecture: Domain-independent HttpServer and SSEPushManager for seamless multi-domain deployments
• Enhanced MCP & AI Support: Overloaded tool methods, schema merging, idle session watchdogs, and auto-cleanup
• ANSI Console Logging: Modern color-coded console logs with Java 9+ StackWalker caller tracing
• Configurable HTTP Timeouts: Custom connect and read timeouts on URLRequest and HTTPHandler
• High Performance: Handling over 86,000 requests per second with ultra-low latency (~17ms)
• Detailed Release Notes: See What's New in 1.7.29 (中文版)

Choose Your Language / 选择语言

English Documentation

• Getting Started
• Core Concepts
• Web Applications
• CLI Applications
• Configuration
• Database Integration
• Advanced Features
• Best Practices
• What's New in 1.7.29
• API Reference
  • Application API
  • Action API
  • Configuration API
  • Database API

中文文档

• 入门指南
• 核心概念
• Web应用开发
• 命令行应用
• 配置说明
• 数据库集成
• 高级特性
• 最佳实践
• 1.7.29 新特性
• API参考
  • 应用程序 API
  • 动作 API
  • 配置 API
  • 数据库 API

Quick Start

Using the tinystruct Archetype

The fastest way to get started is using the tinystruct archetype:

# Follow the archetype to create a project quickly
https://github.com/tinystruct/tinystruct-archetype

Manual Installation

Add the dependency to your pom.xml:

<dependency>
    <groupId>org.tinystruct</groupId>
    <artifactId>tinystruct</artifactId>
    <version>1.7.29</version>
    <classifier>jar-with-dependencies</classifier>
</dependency>

Basic Example

package tinystruct.examples;

import org.tinystruct.AbstractApplication;
import org.tinystruct.ApplicationException;
import org.tinystruct.system.annotation.Action;
import org.tinystruct.system.annotation.Action.Mode;

public class Example extends AbstractApplication {

    @Override
    public void init() {
        // Initialization code
    }

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

    @Action("praise")
    public String praise() {
        return "Praise the Lord!";
    }

    @Action("say")
    public String say(String words) {
        return words;
    }

    // HTTP method-specific actions
    @Action(value = "hello", mode = Mode.HTTP_GET)
    public String helloGet() {
        return "GET";
    }

    @Action(value = "hello", mode = Mode.HTTP_POST)
    public String helloPost() {
        return "POST";
    }
}

Why Choose tinystruct?

Modern Design Philosophy

1. No main() method required - Applications start directly with CLI commands
2. Unified CLI and Web - Write once, run anywhere (CLI or Web)
3. Built-in lightweight HTTP servers - Netty, Tomcat, or Undertow
4. Minimal configuration - No excessive XML or YAML
5. Performance-first architecture - Zero overhead, no reflection-based scanning
6. AI-ready - Designed for AI integration with MCP support

Performance Benchmarks

Running 30s test @ http://127.0.0.1:8080/?q=say/Praise the Lord!
12 threads and 400 connections

Requests/sec:  86753.98
Transfer/sec:  17.46MB
Latency:       17.44ms (avg)

Architecture

tinystruct follows a modular, action-oriented architecture that enables:

• Code reuse between CLI and web applications
• Unified interface through @Action annotation
• Plugin-based extensibility
• Low-latency direct method invocation
• Flexible deployment options (monolithic, microservices, or hybrid)

Contributing / 贡献

If you'd like to contribute to this documentation, please: 如果您想为此文档做出贡献,请：

1. Fork the repository / 复刻仓库
2. Create a new branch for your changes / 创建新的分支
3. Submit a pull request with your improvements / 提交拉取请求

License / 许可证

This documentation is licensed under the same terms as the tinystruct framework (Apache License 2.0). 本文档采用与 tinystruct 框架相同的许可条款。