# Xpring

**Repository Path**: xnors/xpring

## Basic Information

- **Project Name**: Xpring
- **Description**: python后端开发框架,基于flask,利于多人合作
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xpring 框架快速入门

xpring 是一个轻量级 Python Web 框架，提供模块化和装饰器驱动的开发体验。

## 🚀 基础用法

### 1. 创建应用
```python
# main.py
from xpring.interf import Application
from myapp.user_module import UserModule

app = Application(modules=[UserModule])
app.run()
```

### 2. 定义模块
```python
# user_module.py
from xpring.anno import ModulePrefix, ModuleCtrls
from xpring.interf import Module
from .user_controller import UserController

@ModulePrefix("/users")
@ModuleCtrls(UserController)
class UserModule(Module):
    pass
```

### 3. 创建控制器
```python
# user_controller.py
from xpring.interf import Ctrl
from xpring.utils import GetMapping, PostMapping, RouterMap

class UserController(Ctrl):
    def setup_service(self):
        self.users = []  # 简单的内存存储
    
    @property
    def routermap(self) -> RouterMap:
        return [
            GetMapping("/", self.get_users),
            PostMapping("/", self.create_user),
        ]
    
    def get_users(self):
        return {"users": self.users}
    
    def create_user(self, user_data: dict):
        self.users.append(user_data)
        return {"message": "用户创建成功", "user": user_data}
```

## 🔧 核心装饰器

### 模块装饰器
```python
@ModulePrefix("/api/v1")        # 设置路由前缀
@ModuleCtrls(Controller1, Controller2)  # 注册控制器
@WithSessionManager(SessionManager())   # 配置会话管理
```

### 路由装饰器
```python
@property
def routermap(self) -> RouterMap:
    return [
        GetMapping("/users", self.get_users),      # GET 请求
        PostMapping("/users", self.create_user),   # POST 请求
        PutMapping("/users/{id}", self.update_user),   # PUT 请求
        DeleteMapping("/users/{id}", self.delete_user), # DELETE 请求
    ]
```

## 🔐 会话管理

```python
from xpring.utils import SessionManager, get_current_user, SessionData
from fastapi import Depends

# 创建会话管理器
manager = SessionManager()

# 创建会话
session_id = manager.create("username", user_id=123)

# 在路由中获取当前用户
def protected_route(current_user: SessionData = Depends(get_current_user)):
    return {"user": current_user.username}
```

## 📦 项目结构示例

```
myapp/
├── main.py              # 应用入口
├── user_module.py       # 用户模块
├── user_controller.py   # 用户控制器
└── user_service.py      # 用户服务
```

## 🛠️ 常用工具

### 路由注册
```python
from xpring.utils import register_routers
from fastapi import FastAPI

app = FastAPI()
router_map = [GetMapping("/health", lambda: {"status": "ok"})]
register_routers(app, router_map, "/api")
```

### 错误处理 基于([Pyrsult库](http://github.com/fexcode/pyrsult))
```python
from pyrsult import Success, Failure

def handle_result(result):
    match result:
        case Success(data):
            return {"status": "success", "data": data}
        case Failure(error):
            return {"status": "error", "message": str(error)}
```

## 📚 核心概念

- **Application**: 应用程序入口
- **Module**: 功能模块容器  
- **Ctrl**: 请求控制器
- **Service**: 业务逻辑层
- **装饰器**: 简化配置的元编程工具

这就是 xpring 框架的基本用法！