# gua

**Repository Path**: GodanKing/gua

## Basic Information

- **Project Name**: gua
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-09
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gua - Python Web框架

## 为什么选择Gua？

- **10行代码创建完整应用** - 不需要学习复杂的框架概念，直接上手写业务代码
- **自动处理所有响应类型** - 返回什么就是什么，不用手动设置JSON、HTML或文本格式
- **内置实时通信功能** - WebSocket和SSE一行代码实现，无需额外配置
- **零内存占用处理大文件** - 上传GB级文件不占用服务器内存
- **AI应用原生支持** - 逐字流式响应，像ChatGPT一样自然
- **极简CLI工具** - 一键启动应用，自动处理所有配置

## 30秒创建第一个应用

```python
# app.py
from gua import GuaApp, respond

app = GuaApp()

@app.route("/")
async def home():
    return respond("<h1>Hello World</h1>")

@app.route("/api/users/{user_id}")
async def get_user(user_id: int):
    return respond({"user_id": user_id, "name": f"User {user_id}"})
```

```bash
# 安装
pip install https://gitee.com/GodanKing/gua.git

# 启动 - 使用Gua CLI工具（推荐）
gua app:app

# 或者使用传统方式
granian app:app --interface asgi
```

访问 http://localhost:8000 查看效果！

## 安装

### 方式1：使用pip安装（推荐）

```bash
# 基础安装
pip install https://gitee.com/GodanKing/gua.git

# 推荐使用uv（更快的包管理器）
uv add git+https://gitee.com/GodanKing/gua.git

# 安装性能优化版本（包含orjson）
pip install https://gitee.com/GodanKing/gua.git[performance]
```

### 方式2：开发环境安装

```bash
# 克隆仓库
git clone https://gitee.com/GodanKing/gua.git
cd gua

# 安装开发依赖
uv sync

# 或者使用pip
pip install -e ".[dev]"
```

## Gua CLI工具

Gua框架提供了极简的CLI工具，将复杂的granian参数简化为5个核心参数：

### 基础使用

```bash
# 启动应用（自动检测）
gua app:app

# 指定端口
gua app:app --port 3000

# 生产环境
gua app:app --mode prod

# 带静态文件
gua app:app --static ./static --static-route /assets
```

### 运行模式

| 模式 | 说明 | 默认配置 |
|------|------|----------|
| `dev` | 开发环境 | 单进程，热重载 |
| `prod` | 生产环境 | 多进程，无重载 |
| `example` | 示例应用 | 单进程，热重载 |

### 快速启动示例

```bash
# 启动任何示例应用
gua examples.simple_app:app
gua examples.websocket_app:app
gua examples.ai_streaming:app

# 等价于
granian examples.simple_app:app --interface asgi --reload
granian examples.websocket_app:app --interface asgi --reload
granian examples.ai_streaming:app --interface asgi --reload
```

### 完整参数说明

```bash
gua [app] [options]

参数：
  app                  应用标识符（如：app:app），默认自动检测
  --port, -p           端口号（默认：8000）
  --host               主机地址（默认：0.0.0.0）
  --mode, -m           运行模式：dev/prod/example（默认：dev）
  --workers, -w        工作进程数（默认：模式自动设置）
  --static             静态文件目录路径
  --static-route       静态文件路由前缀（默认：/static）
  --dry-run            显示命令而不执行
  --version            显示版本信息
  --                   透传granian参数
```

## 实际应用场景

### 场景1：快速构建网站和API

**用途**：快速搭建个人网站、博客、API服务，无需学习复杂的框架概念。

**示例：个人博客**
```python
from gua import GuaApp, respond

app = GuaApp()

@app.route("/")
async def home():
    return respond("<h1>我的博客</h1><p>欢迎访问我的个人博客</p>")

@app.route("/api/posts")
async def list_posts():
    return respond([
        {"id": 1, "title": "第一篇文章", "content": "..."},
        {"id": 2, "title": "第二篇文章", "content": "..."}
    ])

@app.route("/api/posts/{post_id}")
async def get_post(post_id: int):
    return respond({"id": post_id, "title": f"文章{post_id}", "content": "文章内容..."})
```

**示例：REST API服务**
```python
from gua import GuaApp, respond, error

app = GuaApp()

@app.route("/api/users", ["GET", "POST"])
async def users():
    if request.method == "GET":
        return respond({"users": []})
    else:
        return respond({"message": "用户创建成功"}, status=201)

@app.route("/api/users/{user_id}")
async def get_user(user_id: int):
    if user_id > 1000:
        return error("用户不存在", 404)
    return respond({"id": user_id, "name": f"用户{user_id}"})
```

### 场景2：实现实时通信

**用途**：构建聊天室、实时通知、在线协作功能，让多个用户同时交互。

**示例：聊天室**
```python
from gua import GuaApp, respond, create_websocket_manager, ws_text

app = GuaApp()
ws_manager = create_websocket_manager()

@app.websocket("/ws")
async def chat_websocket(scope: Scope, receive: Receive, send: Send):
    await ws_text(send, "accept")
    ws_manager.add(send)
    
    try:
        while True:
            message = await receive()
            if message["type"] == "websocket.receive":
                # 广播消息给所有连接的用户
                await ws_manager.broadcast({
                    "type": "message",
                    "data": message["text"],
                    "time": time.time()
                })
    finally:
        ws_manager.remove(send)

@app.route("/")
async def chat_page():
    return respond("""
    <h1>聊天室</h1>
    <div id="messages"></div>
    <input id="input" placeholder="输入消息...">
    <button onclick="send()">发送</button>
    <script>
        const ws = new WebSocket('ws://localhost:8000/ws');
        ws.onmessage = e => {
            const msg = JSON.parse(e.data);
            document.getElementById('messages').innerHTML += 
                `<p>${msg.data}</p>`;
        };
        function send() {
            const input = document.getElementById('input');
            ws.send(input.value);
            input.value = '';
        }
    </script>
    """)
```

**示例：实时状态更新**
```python
from gua import GuaApp, respond, create_sse_manager

app = GuaApp()
sse_manager = create_sse_manager()

@app.route("/events")
async def status_updates():
    """实时推送服务器状态"""
    async def status_generator():
        while True:
            await sse_manager.broadcast({
                "event": "status",
                "data": {
                    "cpu": random.randint(10, 90),
                    "memory": random.randint(20, 80),
                    "time": time.time()
                }
            })
            await asyncio.sleep(2)
    
    # 启动后台任务
    asyncio.create_task(status_generator())
    
    # 返回SSE连接
    from gua import sse
    return sse().start({"message": "连接成功"}).build()

@app.route("/")
async def dashboard():
    return respond("""
    <h1>服务器状态监控</h1>
    <div id="status">等待数据...</div>
    <script>
        const eventSource = new EventSource('/events');
        eventSource.onmessage = e => {
            const data = JSON.parse(e.data);
            document.getElementById('status').innerHTML = 
                `CPU: ${data.cpu}% | 内存: ${data.memory}%`;
        };
    </script>
    """)
```

### 场景3：处理流式数据

**用途**：处理大文件传输、实时数据展示，避免内存溢出和长时间等待。

**示例：文件上传**
```python
from gua import GuaApp, respond, file_handler

app = GuaApp()

@app.route("/upload", ["POST"])
async def upload_file(request):
    """处理大文件上传，零内存占用"""
    file_info = await file_handler.save_stream(request)
    return respond({
        "message": "文件上传成功",
        "filename": file_info["filename"],
        "size": file_info["size"]
    })

@app.route("/download/{filename}")
async def download_file(filename):
    """文件下载"""
    return file_handler.send_file(f"./uploads/{filename}")
```

**示例：实时数据流**
```python
from gua import GuaApp, stream

app = GuaApp()

@app.route("/live-data")
async def live_data():
    """实时推送数据，适合数据可视化"""
    return (
        stream()
        .range(1, 100, 0.1)  # 每0.1秒发送一个数字
        .build()
    )

@app.route("/progress")
async def progress_tracker():
    """模拟长时间任务的进度更新"""
    return (
        stream()
        .json({"status": "开始处理", "progress": 0}, 1)
        .json({"status": "处理中", "progress": 25}, 2)
        .json({"status": "处理中", "progress": 50}, 2)
        .json({"status": "处理中", "progress": 75}, 2)
        .json({"status": "完成", "progress": 100}, 1)
        .build()
    )
```

### 场景4：构建AI应用

**用途**：实现类似ChatGPT的流式对话、AI助手，提供流畅的用户体验。

**示例：AI聊天机器人**
```python
from gua import GuaApp, respond, stream

app = GuaApp()

@app.route("/chat")
async def chat_stream(request):
    """AI流式对话，逐字显示回复"""
    # 获取用户消息
    user_message = request.query_params.get("message", "")
    
    # 模拟AI思考
    await asyncio.sleep(1)
    
    # 生成AI回复
    ai_response = f"您说：'{user_message}'。这是一个很好的问题，让我来详细解答..."
    
    # 逐字流式返回
    return (
        stream()
        .text(ai_response, 0.05)  # 每0.05秒显示一个字符
        .build()
    )

@app.route("/")
async def chat_interface():
    return respond("""
    <h1>AI助手</h1>
    <div id="response"></div>
    <input id="input" placeholder="输入您的问题...">
    <button onclick="ask()">提问</button>
    <script>
        async function ask() {
            const input = document.getElementById('input');
            const response = document.getElementById('response');
            response.innerHTML = '';
            
            const eventSource = new EventSource(`/chat?message=${encodeURIComponent(input.value)}`);
            
            eventSource.onmessage = e => {
                response.innerHTML += e.data;
            };
            
            input.value = '';
        }
    </script>
    """)
```

### 场景5：文件处理

**用途**：构建文件分享系统、批量处理工具，支持各种文件操作。

**示例：文件分享系统**
```python
from gua import GuaApp, respond, file_handler

app = GuaApp()

@app.route("/")
async def file_list():
    """显示文件列表"""
    import os
    files = os.listdir("./uploads")
    file_links = [f'<a href="/download/{f}">{f}</a>' for f in files]
    return respond(f"""
    <h1>文件分享</h1>
    <form action="/upload" method="post" enctype="multipart/form-data">
        <input type="file" name="file">
        <button type="submit">上传</button>
    </form>
    <h2>文件列表</h2>
    {"".join(file_links)}
    """)

@app.route("/upload", ["POST"])
async def upload_file(request):
    """处理文件上传"""
    file_info = await file_handler.save_stream(request)
    return respond({"message": "上传成功", "filename": file_info["filename"]})

@app.route("/download/{filename}")
async def download_file(filename):
    """文件下载"""
    return file_handler.send_file(f"./uploads/{filename}")
```

## 日志系统

Gua框架内置了基于Linus设计哲学的极简日志系统：

### 基础日志使用

```python
from gua import GuaApp, respond, get_default_logger

app = GuaApp()
logger = get_default_logger()

@app.route("/api/data")
async def get_data():
    logger.log("info", "data_request", "获取数据请求", user_id=123)
    return respond({"data": "敏感数据"})
```

### 高级日志配置

```python
from gua import GuaApp, GuaLogger, LoggingMiddleware

# 创建自定义日志器
logger = GuaLogger("my_app", output="file", file_path="app.log")

# 应用日志中间件
app = GuaApp()
app.use(LoggingMiddleware(logger, slow_threshold=1.0))
```

### 性能监控

```python
from gua import SimpleMonitor, get_default_logger

logger = get_default_logger()
monitor = SimpleMonitor(logger)

# 记录请求性能
monitor.record_request(duration=0.5, is_error=False)

# 获取统计信息
stats = monitor.get_stats()
# 返回: {"avg_response_time": 0.45, "max_response_time": 1.2, "error_rate": 0.05}
```

## 常见问题

### 如何添加认证？

```python
from gua import GuaApp, respond, auth

app = GuaApp()

# 默认保护所有路径，只列出公开路径
app.use(auth(public_paths=["/login", "/register", "/health"]))

@app.route("/admin")
async def admin_panel():
    return respond({"message": "管理员面板"})

@app.route("/login")
async def login():
    return respond({"message": "登录页面"})  # 公开访问，无需认证

@app.route("/api/users")
async def users():
    return respond({"users": ["alice", "bob"]})  # 需要认证
```

### 如何处理错误？

```python
from gua import GuaApp, respond, error

app = GuaApp()

@app.route("/api/data")
async def get_data():
    if not user_authenticated():
        return error("未授权访问", 401)
    return respond({"data": "敏感数据"})
```

### 如何部署到生产环境？

```bash
# 使用Gua CLI部署（推荐）
gua app:app --mode prod --workers 4

# 使用传统方式
granian app:app --interface asgi --workers 4

# 使用Docker
docker build -t my-gua-app .
docker run -p 8000:8000 my-gua-app

# 使用环境变量配置
export GUA_HOST=0.0.0.0
export GUA_PORT=8000
export GUA_WORKERS=4
gua app:app --mode prod
```

### 如何配置静态文件？

```bash
# 开发环境
gua app:app --static ./static --static-route /assets

# 生产环境
gua app:app --mode prod --static /var/www/static --static-route /files
```

## 更多示例

查看 `examples/` 目录中的完整示例：
- `simple_app.py` - 基础Web应用
- `websocket_app.py` - WebSocket聊天室
- `ai_streaming.py` - AI流式对话
- `streaming_api.py` - 流式数据API
- `file_streaming.py` - 文件流处理
- `auth_demo.py` - 认证中间件演示
- `logging_demo.py` - 日志系统演示

## 更多文档

### 核心指南
- [极简API指南](docs/极简API指南.md) - 掌握Gua框架的核心API设计
- [认证中间件指南](docs/认证中间件指南.md) - 了解"默认保护，明确例外"的认证设计
- [JSON配置指南](docs/JSON配置指南.md) - 配置JSON处理和性能优化
- [Gua CLI设计文档](docs/gua-cli设计文档.md) - 深入了解CLI工具设计

### 流式处理系列
- [流式处理快速开始](docs/流式处理/流式处理快速开始.md) - 快速上手流式功能
- [流式处理框架设计](docs/流式处理/流式处理框架设计.md) - 深入了解流式架构设计
- [流式处理最佳实践](docs/流式处理/流式处理最佳实践.md) - 生产环境流式处理建议
- [Gua框架流式处理实现](docs/流式处理/Gua框架流式处理实现.md) - 流式功能实现细节