nb_api
⚡️ 为你的数据模型闪电般地生成 CRUD API ⚡️
🚀 nb_api 是什么?
nb_api 是一个为现代 FastAPI 应用量身打造的 CRUD 路由自动生成框架。你只需定义好你的数据模型,nb_api 就能为你自动创建一整套完整、健壮且文档齐全的增、删、改、查(CRUD)API 接口。
nb_api 旨在解决为 FastAPI 应用重复编写 CRUD 接口的痛点。它支持多种数据存储后端,提供了更强大、更现代化的功能。
✨ 核心优势
- 多数据库支持: 支持 SQLModel、SQLAlchemy、Tortoise ORM 和 内存存储,满足不同场景需求
- 现代化技术栈: 完全基于 FastAPI + Pydantic v2 构建,享受最新的性能优化和最完善的类型提示
- 高度自动化: 告别重复编写 CRUD 样板代码,让你专注于核心业务逻辑
- 强大的搜索能力: 内置"超级搜索"接口,允许前端通过 JSON 动态构建复杂的过滤和排序查询
- 规范的 API 设计: 所有响应都封装在统一的
ResponseModel中,无论是成功还是失败,都有一致的结构,极大简化了前端处理 - 生产级特性: 开箱即用的分页、依赖注入、慢请求日志记录等功能,让你的应用兼具开发效率和生产环境下的可观测性
- 灵活可扩展: 轻松禁用、覆盖默认路由,或添加自定义路由,满足你的所有特殊需求
🛠️ 安装
pip install very_nb_api fastapi sqlmodel uvicorn
注意安装和实际导入不同,因为提示nb_api这个名字和pypi已存在的包相似冲突了
安装
pip install very_nb_api
导入
import nb_api
快速开始
SQLModel 版本
在短短十几行代码内,即可拥有一个功能完备的 CRUD API。
# main.py
from typing import Optional
from sqlmodel import Field, Session, SQLModel, create_engine
from fastapi import FastAPI
from nb_api import SQLModelCRUDRouter
# 1. 定义 SQLModel 模型
class Book(SQLModel, table=True):
id: Optional[int] = Field(default=None, primary_key=True)
title: str
author: str
# 2. 设置数据库
engine = create_engine("sqlite:///database.db")
def get_session():
with Session(engine) as session:
yield session
# 3. 创建 FastAPI 应用和 nb_api 路由
app = FastAPI()
@app.on_event("startup")
def on_startup():
SQLModel.metadata.create_all(engine)
# 核心用法!
app.include_router(
SQLModelCRUDRouter(schema=Book, db_model=Book, db_session=get_session)
)
异步 SQLModel 版本
# main.py
from typing import Optional, AsyncGenerator
from sqlmodel import Field, SQLModel
from sqlalchemy.ext.asyncio import create_async_engine
from sqlmodel.ext.asyncio.session import AsyncSession
from fastapi import FastAPI
from nb_api import AioSQLModelCRUDRouter
# 1. 定义 SQLModel 模型
class Book(SQLModel, table=True):
id: Optional[int] = Field(default=None, primary_key=True)
title: str
author: str
# 2. 设置异步数据库
DATABASE_URL = "sqlite+aiosqlite:///database.db"
engine = create_async_engine(DATABASE_URL)
async def get_session() -> AsyncGenerator[AsyncSession, None]:
async with AsyncSession(engine) as session:
yield session
# 3. 创建 FastAPI 应用和 nb_api 路由
app = FastAPI()
# 核心用法!
app.include_router(
AioSQLModelCRUDRouter(schema=Book, db_model=Book, db=get_session)
)
Tortoise ORM 版本
# main.py
from typing import Optional
from tortoise.models import Model
from tortoise import fields
from tortoise.contrib.fastapi import register_tortoise
from fastapi import FastAPI
from pydantic import BaseModel
from nb_api import TortoiseCRUDRouter
# 1. 定义 Tortoise ORM 模型
class Book(Model):
id = fields.IntField(pk=True)
title = fields.CharField(max_length=100)
author = fields.CharField(max_length=100)
# 2. 定义 Pydantic 模型
class BookSchema(BaseModel):
id: int
title: str
author: str
class Config:
from_attributes = True
# 3. 创建 FastAPI 应用
app = FastAPI()
# 4. 注册 Tortoise ORM
register_tortoise(
app,
db_url="sqlite://db.sqlite3",
modules={"models": ["__main__"]},
generate_schemas=True,
add_exception_handlers=True
)
# 核心用法!
app.include_router(
TortoiseCRUDRouter(schema=BookSchema, db_model=Book, prefix="books")
)
内存版本(无需数据库)
# main.py
from typing import Optional
from pydantic import BaseModel
from fastapi import FastAPI
from nb_api import MemoryCRUDRouter
# 1. 定义 Pydantic 模型
class Book(BaseModel):
id: Optional[int] = None
title: str
author: str
# 2. 创建 FastAPI 应用
app = FastAPI()
# 核心用法!
app.include_router(
MemoryCRUDRouter(schema=Book, prefix="books")
)
启动应用 uvicorn main:app --reload,然后访问 http://127.0.0.1:8000/docs,你将看到 nb_api 为 Book 模型自动生成的所有接口!
🌟 功能展示
1. 自动生成的 CRUD 路由
| 路由 | 方法 | 描述 |
|---|---|---|
/book |
GET |
获取所有书籍 (支持分页) |
/book |
POST |
创建一本新书 |
/book |
DELETE |
删除所有书籍 |
/book/{item_id} |
GET |
获取指定 ID 的书籍 |
/book/{item_id} |
PUT |
更新指定 ID 的书籍 |
/book/{item_id} |
DELETE |
删除指定 ID 的书籍 |
/book/search |
POST |
超级搜索接口 |
2. 超级搜索接口 (/search)
这是 nb_api 的独有功能!通过一个 POST 请求,实现复杂的动态查询。
请求: POST /book/search
请求体:
{
"filters": [
{ "field": "author", "operator": "contains", "value": "Tolkien" },
{ "field": "id", "operator": "in", "value": [1, 3, 5] }
],
"sorting": [
{ "field": "title", "direction": "asc" }
]
}
3. 统一的 API 响应
成功响应:
{
"status_code": 0,
"msg": "success",
"data": { "id": 1, "title": "The Hobbit", "author": "J.R.R. Tolkien" }
}
错误响应:
{
"status_code": 404,
"msg": "Item not found"
}
4. 路由定制与扩展
nb_api 提供了丰富的初始化参数来定制路由行为。
from fastapi import Depends
router = SQLModelCRUDRouter(
schema=Book,
db_model=Book,
db_session=get_session,
# --- 功能配置 ---
paginate=50, # 设置分页最大数量
# --- 路由控制 ---
prefix="my-books", # 自定义路由前缀
tags=["图书管理"], # 自定义 OpenAPI 标签
delete_all_route=False, # 禁用"删除所有"路由
# --- 依赖注入 (权限控制) ---
update_route=[Depends(require_admin_user)],
create_route=[Depends(require_login)]
)
你也可以像使用普通的 APIRouter 一样,轻松地覆盖或添加新路由。
# 覆盖默认的 get_one 路由
@router.get("/{item_id}")
def custom_get_one(item_id: int):
return {"message": f"You are viewing book {item_id} with a custom route!"}
# 添加一个全新的路由
@router.post("/{item_id}/publish")
def publish_book(item_id: int):
# ... 发布逻辑 ...
return {"message": "Book published!"}
5 一个接口没写,下面都是nb_api自动生成的接口
这些接口都是nb_api自动生成的,你只需要定义好你的数据模型,nb_api就会自动生成这些接口,全部都不是人工手写def 的 fastapi 接口
Metadata
Release files for very-nb-api 0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| very_nb_api-0.7.tar.gz | 19.6 kB | Without provenance | Details for very_nb_api-0.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| very_nb_api-0.7-py3-none-any.whl | Python 3 | none | any | Details for very_nb_api-0.7-py3-none-any.whl |
Total release size: 42.9 kB
Release files / very_nb_api-0.7.tar.gz
| Download URL | very_nb_api-0.7.tar.gz |
|---|---|
| Size | 19.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52e31de22aa4cdb189ab1f049d008a9ef93dcbce1ea021af7a017f166682b84b
|
|
BLAKE2b-256 checksum How to use checksums |
27e7cd58d76f1dc14f2fd11b9a5dd20dc13af04dd5c029daea8a0be36ce71de8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.0
|
Release files / very_nb_api-0.7-py3-none-any.whl
| Download URL | very_nb_api-0.7-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b292d509b69509a88e01f4c896434ca7ff6be60c3794de166a401e5b9a92eb3
|
|
BLAKE2b-256 checksum How to use checksums |
131cf13409e384948fb179b4e3ee7d9181ff3f7ee5880b7ccd218e9add8b3dec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.0
|
Security for very-nb-api 0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.