Skip to content

Latest commit

 

History

History
205 lines (149 loc) · 4.07 KB

core-concepts.md

File metadata and controls

205 lines (149 loc) · 4.07 KB

核心概念

框架哲学

tinystruct 遵循以下核心设计准则：

  1. 无需 main() 方法 - 通过命令行指令直接启动应用。
  2. 统一 CLI 和 Web 设计 - 编写一次代码，即可在命令行和 Web 环境中运行。
  3. 内置轻量级服务器 - 默认支持 Netty, Tomcat 和 Undertow。
  4. 极简配置 - 避免过度使用 XML 或 YAML 配置文件。
  5. 性能优先架构 - 专注于高吞吐量和超低延迟。
  6. AI 就绪 - 内置对 MCP 模型上下文协议的支持。

应用结构

AbstractApplication

所有 tinystruct 应用的基类。它提供：

  • 配置管理
  • 动作处理
  • 请求/响应处理
  • 数据库连接
public class MyApp extends AbstractApplication {
    @Override
    public void init() {
        // 初始化应用
    }

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

动作（Actions）

动作是 tinystruct 应用的核心构建块。它们同时处理 Web 请求和 CLI 命令。

Action 注解

@Action(
    value = "endpoint",           // URL模式或命令名称
    description = "描述",         // 动作描述
    mode = Action.Mode.ALL       // 执行模式（ALL、WEB、CLI）
)

URL 模式

@Action("users")    // 自动匹配 /users、/users/123、/users/123/posts

Tinystruct 会根据 URL 模式自动匹配正确的功能。无需在 @Action 注解中定义像 {id} 这样的变量。框架会根据参数智能地将请求路由到适当的方法。

配置

属性文件

# 应用设置
application.name=MyApp
application.mode=development

# 服务器设置
server.port=8080
server.host=localhost

# 数据库设置
database.type=MySQL
database.url=jdbc:mysql://localhost:3306/mydb

访问配置

String appName = getConfiguration().get("application.name");
int port = Integer.parseInt(getConfiguration().get("server.port"));

数据库集成

仓库类型

  • MySQL
  • SQLite
  • H2
  • Redis
  • Microsoft SQL Server

基本用法

Repository repository = Type.MySQL.createRepository();
repository.connect(getConfiguration());

// 执行查询
List<Row> results = repository.query("SELECT * FROM users");

// 执行更新
repository.execute("UPDATE users SET name = ? WHERE id = ?",
                  "张三", 1);

请求处理

Web 请求

@Action("api/data")
public String getData(Request request, Response response) {
    String param = request.getParameter("key");

    // 设置内容类型为 JSON
    response.headers().add(Header.CONTENT_TYPE.set("application/json"));

    // 创建 JSON 响应
    Builder builder = new Builder();
    builder.put("key", param);

    return builder.toString();
}

CLI 命令

@Action(value = "generate",
        description = "生成 POJO 对象",
        mode = Action.Mode.CLI)
public void generate() {
    // 命令实现
}

安全性

身份验证

@Action("secure/endpoint")
public Response secureEndpoint(Request request) {
    if (!isAuthenticated(request)) {
        throw new UnauthorizedException();
    }
    // 受保护的代码
}

授权

@Action("admin/users")
public Response adminOnly(Request request) {
    if (!hasRole(request, "ADMIN")) {
        throw new ForbiddenException();
    }
    // 仅管理员代码
}

错误处理

try {
    // 您的代码
} catch (ApplicationException e) {
    logger.log(Level.SEVERE, e.getMessage(), e);
    throw new ApplicationRuntimeException(e.getMessage(), e);
}

AI 集成

tinystruct 已经为现代 AI 应用做好准备，通过对 MCP (Model Context Protocol) 的支持，您可以轻松集成 AI 功能。

MCP 配置

在 config.properties 中配置您的认证令牌：

mcp.auth.token=YOUR_TOKEN_HERE

AI 动作示例

@Action("ai/chat")
public String chat(String message) {
    return aiService.processMessage(message);
}

下一步