FastAPI 的声明式增强框架。一个 @all 装饰器 = HTTP + MCP + SSE + WebSocket 四协议全部就绪。
Project description
🏗️ Pointend
FastAPI 的声明式增强框架。一个 @all 装饰器 = HTTP + MCP + SSE + WebSocket 四协议全部就绪。
✅ CI 已通过 | 测试覆盖 92% | 本地 100+ 测试全部通过
快速开始 • 功能矩阵 • 文档中心 • 为什么选择 Pointend? • 贡献指南
✨ 功能矩阵
| 能力维度 | 全覆盖能力 |
|---|---|
| 🏗️ 声明式装饰器 (8+1) | @service_for · @endpoint · @mcp_tool · @mcp_for · @listen_for · @publish_event · @scheduled · @ws_endpoint · @all 超级组合 |
| 🔌 多协议统一 | HTTP REST · MCP AI 工具 · SSE 事件流 · WebSocket · WebMCP (草案) |
| 📦 四层代码生成 | SQLAlchemy Schema · BaseRepo · BaseService · Router 全栈静态生成 |
| ⚡ 极致性能 | Rust 核心加速 (10x) · Mako 模板预编译 · 指纹增量生成 (2.6ms) · SSD 批量并行写入 |
| 🤖 AI 原生设计 | MCP 双通道 · AI 宪法引导器 · A2UI 前端生成 · llm.txt 标准 |
| 🛡️ 生产级加固 | strict=True 默认 · 多层安全中间件 · 完整审计日志 · 宪法式编程引擎 |
| ♻️ 自治自增长 | 自动版本检测 · 快照备份机制 · 六步迁移工具链 · 智能 Bug 上报 |
| 🧪 测试保障 | 1000+ 测试点 · 6 维度全覆盖 · 核心模块 100% · 整体 92% 覆盖率 |
🚀 快速开始
三步跑起来
# 1. 创建新项目（交互式向导）
pointend new my-app
# 2. 进入项目并安装依赖
cd my-app && uv sync
# 3. 启动！自动生成 CRUD + Swagger + MCP
uv run uvicorn main:app --reload
30 秒后：
- 🌐 访问 http://localhost:8000/docs → 完整 Swagger 文档
- 🤖 AI 助手已可直接调用全部 MCP 工具
30 秒手写版
# main.py
from fastapi import FastAPI
from sqlalchemy.orm import Mapped, mapped_column
from pointend import (
service_for, endpoint, mcp_tool,
auto_setup_all, Base
)
# 1. 定义数据模型（标准 SQLAlchemy）
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str]
email: Mapped[str]
# 2. 写业务逻辑（加装饰器即完成）
@service_for(User)
class UserService:
@endpoint("POST") # 自动暴露为 HTTP POST
@mcp_tool(category="user") # 自动暴露为 MCP 工具
async def register(self, name: str, email: str):
"""注册新用户"""
return {"id": 1, "name": name, "email": email}
# 3. 启动！
app = FastAPI(title="我的应用")
auto_setup_all(app)
🎯 装饰器速查表
8 个标准装饰器 + 1 个超级组合装饰器
| 装饰器 | 用途 | 一行示例 |
|---|---|---|
@service_for(Entity) |
声明为实体的 Service 层 | @service_for(User) |
@endpoint(method, path) |
注册为 HTTP 端点 | @endpoint("POST", "/users") |
@mcp_tool(category) |
暴露为 AI 可调用工具 | @mcp_tool(category="user") |
@mcp_for(Entity) |
为实体生成全套 CRUD 工具 | @mcp_for(User) |
@listen_for(channel) |
注册为事件监听器 | @listen_for("user.created") |
@publish_event(channel) |
返回值自动发布为事件 | @publish_event("user.created") |
@scheduled(every) |
注册为定时任务 | @scheduled(every="5m") |
@ws_endpoint(path) |
注册为 WebSocket 端点 | @ws_endpoint("/ws/realtime") |
@all(...) |
超级组合，一次声明多端生效 | @all(method="POST", category="user") |
📁 项目架构
src/pointend/
├── __init__.py # 包主入口，导出全部API
├── lifecycle.py # 生命周期管理 + auto_setup_all
├── bases_generated.py # ✨ 自动生成，请勿手动修改
│
├── core/ # 🧠 核心层
│ ├── registry.py # 七大全局注册表
│ ├── bases.py # 抽象接口（Cache/EventBus/Auth）
│ ├── repo.py # BaseRepo（继承 FastCRUD）
│ ├── config.py # 配置系统（四层优先级）
│ ├── scanner.py # 多进程并行实体扫描器
│ ├── adapters.py # 后端自动适配降级
│ ├── health_scorer.py # 启动健康评分
│ ├── backup_manager.py # 全量快照备份
│ ├── migration_checker.py # 六步迁移检查
│ └── architecture_reviewer.py # 架构合规审查
│
├── decorators/ # 🎨 装饰器层
│ ├── service.py # @service_for
│ ├── endpoint.py # @endpoint
│ ├── mcp.py # @mcp_tool, @mcp_for
│ ├── event.py # @listen_for, @publish_event
│ ├── scheduled.py # @scheduled
│ ├── websocket.py # @ws_endpoint
│ └── all_in_one.py # @all 超级装饰器
│
├── builder/ # 🔧 代码生成层
│ ├── codegen.py # BaseService 代码生成器
│ ├── fingerprint.py # SHA256 增量指纹计算
│ └── templates/ # Mako 模板目录
│
├── plugins/ # 🔌 插件层
│ ├── redis_cache.py # Redis 缓存后端
│ ├── memory_cache.py # 内存缓存后端
│ ├── pg_event_bus.py # PostgreSQL 事件总线
│ └── fastapi_mcp_adapter.py # FastAPI MCP 集成
│
├── cli/ # ⌨️ 命令行工具
│ ├── scaffold.py # pointend new 脚手架
│ ├── migrate.py # 版本迁移工具
│ └── wizard.py # 交互式配置向导
│
└── ai/ # 🤖 AI 增强层
├── enhancer.py # 文档字符串自动增强
└── constitution.py # Pointend 开发宪法
📚 文档中心
| 文档类型 | 链接 |
|---|---|
| 📖 模块技术文档 | docs/modules/README.md |
| 🧪 测试覆盖矩阵 | docs/TEST_COVERAGE_MATRIX.md |
| 📋 完整 68 项能力清单 | docs/FULL_CAPABILITIES.md |
| 🏛️ 核心架构设计 | ARCHITECTURE_CORE.md |
| 📋 详细技术实现 | POINTEND_DETAILED_DOC_v2.md |
| 🔄 变更日志 | CHANGELOG.md |
| 📜 历史版本归档 | docs/archive/README.md |
| 🤝 贡献指南 | CONTRIBUTING.md |
| 📜 行为准则 | CODE_OF_CONDUCT.md |
| 🔒 安全政策 | SECURITY.md |
🆚 为什么选择 Pointend?
一句话总结
Pointend = FastAPI + FastCRUD + fastapi-mcp + 声明式开发 + AI 原生 + 自治自增长。
Python 生态横向对比
| 特性 | Pointend | FastAPI 原生 | FastAPI + FastCRUD | fastapi-mcp |
|---|---|---|---|---|
| 声明式装饰器 | ✅ 8+1 个标准化 | ❌ 手动 | ❌ | ❌ |
| MCP AI 原生 | ✅ 深度集成 | ❌ 自己写 | ❌ | ✅ 单独 |
| 四层代码生成 | ✅ Schema→Repo→Service→Router | ❌ 手动 | ✅ 仅 CRUD | ❌ |
| 事件驱动架构 | ✅ 内置 | ❌ 第三方 | ❌ | ❌ |
| 迁移安全工具链 | ✅ 完整六步保障 | ❌ 手动 | ❌ | ❌ |
| 自治自诊断 | ✅ 健康评分 A/B/C/D | ❌ | ❌ | ❌ |
| 代码行数 | ~5000 行 |
🤝 贡献
我们欢迎所有形式的贡献！特别适合新贡献者的任务：
- 🐛 Good First Issue: 标签为
good first issue的简单任务 - 📚 文档改善: 完善模块文档和使用示例
- 🧪 测试增强: 帮助我们达到 98% 的模块覆盖率
- 💡 功能提议: 分享你的想法和使用场景
请阅读 贡献指南 了解完整的开发环境设置、代码规范和 PR 提交流程。
📜 许可证
本项目采用 MIT License 开源许可证。
如果这个项目对你有帮助，请给我们一个 ⭐ Star
Made with ❤️ by the Pointend Team
