想要用Next.js式的开发体验，但后端必须用Python来驱动核心业务逻辑？Krock作为一个全新的混合全栈框架，将Python WSGI后端的纯粹与高效，和React 19及TypeScript的现代前端组件化理念无缝融合，为你提供一个超高速的一体化开发方案。
🔄 Krock 核心工作流程：Python与React的协奏曲
下面这张流程图为你揭示了Krock框架内部，从请求发起到页面呈现的双引擎协作机制。
这个流程展示了Krock如何将前后端统一到一个项目中。你只需在pages目录下创建.tsx文件构建界面，在pages/api目录下创建.py文件处理后端逻辑，框架会自动为你处理路由、打包和热重载。
🧩 项目基石：文件系统即路由
Krock借鉴了Next.js的核心理念：文件系统即路由。你不需要手动配置任何路由规则，项目结构本身就定义了应用的所有路径。
krock/├── pages/ # 前端页面 & 后端API│ ├── api/ # Python API路由│ │ └── todos.py # 自动映射为 /api/todos│ ├── layout.tsx # 全局React布局包装器│ ├── globals.css # 全局CSS & Tailwind导入│ └── index.tsx # 首页（/）├── components/ # 可复用的React组件├── alembic/ # 数据库迁移脚本├── db.py # 数据库连接设置├── models.py # SQLAlchemy ORM模型├── core.py # 核心路由 & WSGI引擎（勿手动修改）└── run.py # 开发服务器和热重载器
在pages/下创建一个about.tsx文件，它就会自动成为/about路由。
在pages/api/下创建一个hello.py文件，它就会自动成为/api/hello的API端点。
🎨 前端构建：React组件与页面
前端开发完全基于React 19和TypeScript，配合esbuild进行极速打包，Tailwind CSS则提供了实用优先的样式方案。
创建全局布局 (pages/layout.tsx)：
// pages/layout.tsximport "./globals.css"; // 导入Tailwind CSS指令export default function Layout({ children }) { return ( <divclassName="min-h-screen bg-gray-50"> <navclassName="bg-white shadow p-4 mb-6"> <h1className="text-xl font-bold text-blue-600">我的Krock应用</h1> </nav> <mainclassName="max-w-4xl mx-auto p-4">{children}</main> </div> );}
layout.tsx是一个特殊文件，它会包裹所有页面组件，非常适合放置导航栏、页脚等全局元素。
创建页面组件 (pages/index.tsx)：
// pages/index.tsximport React, { useState, useEffect } from "react";export default function Home() { const [message, setMessage] = useState("加载中..."); useEffect(() => { // 调用Python后端API fetch("/api/hello") .then((res) => res.json()) .then((data) => setMessage(data.message)); }, []); return ( <divclassName="text-center"> <h2className="text-2xl font-semibold text-gray-800">欢迎使用Krock</h2> <pclassName="mt-4 text-lg text-green-600">{message}</p> </div> );}
⚙️ 后端逻辑：Python API路由
任何放入pages/api/目录的.py文件都会成为一个API端点。每个文件需要导出一个handler函数，接收WSGI标准的environ和params参数。
基础GET与POST处理 (pages/api/hello.py)：
# pages/api/hello.pyimport jsondef handler(environ, params): # environ 包含所有标准WSGI请求数据 method = environ.get("REQUEST_METHOD", "GET") if method == "GET": return {"message": "你好，来自Python后端！"} if method == "POST": # 读取JSON请求体 content_length = int(environ.get("CONTENT_LENGTH", 0)) body = environ["wsgi.input"].read(content_length) data = json.loads(body) return {"status": "success", "received": data}
带数据库交互的CRUD API (pages/api/todos.py)：
# pages/api/todos.pyimport jsonfrom models import Todofrom db import SessionLocaldef handler(environ, params): method = environ.get("REQUEST_METHOD", "GET") db = SessionLocal() try: if method == "GET": todos = db.query(Todo).all() return { "todos": [ {"id": t.id, "title": t.title, "completed": t.completed} for t in todos ] } if method == "POST": content_length = int(environ.get("CONTENT_LENGTH", 0)) body = environ["wsgi.input"].read(content_length) data = json.loads(body) new_todo = Todo(title=data["title"], completed=False) db.add(new_todo) db.commit() return {"status": "created", "id": new_todo.id} finally: db.close()
🗄️ 数据持久化：SQLAlchemy与Alembic
Krock预配置了SQLAlchemy作为ORM，Alembic作为数据库迁移工具，默认使用SQLite，但可以轻松切换到PostgreSQL或MySQL。
定义数据模型 (models.py)：
# models.pyfrom sqlalchemy import Column, Integer, String, Booleanfrom db import Baseclass Todo(Base): __tablename__ = "todos" id = Column(Integer, primary_key=True) title = Column(String, nullable=False) completed = Column(Boolean, default=False)
数据库连接配置 (db.py)：
# db.pyimport osfrom sqlalchemy import create_enginefrom sqlalchemy.orm import sessionmaker, declarative_base# 默认使用SQLite，可通过环境变量切换DATABASE_URL = os.getenv( "DATABASE_URL", "sqlite:///todos.db")engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)Base = declarative_base()
当你修改了models.py后，只需执行以下命令即可自动生成并应用数据库迁移：
# 生成迁移脚本alembic revision --autogenerate -m "描述你的修改"# 应用迁移到数据库alembic upgrade head
如需切换到PostgreSQL，只需安装psycopg2-binary并修改DATABASE_URL：
# PostgreSQL示例DATABASE_URL = "postgresql://user:password@localhost/dbname"
💡 现代化开发体验
热重载：修改React组件、CSS或Python后端文件后，应用会瞬间刷新，无需手动重启。
Tailwind CSS深度集成：直接在.tsx文件中编写Tailwind工具类，框架会自动打包CSS并注入页面，消除未样式化内容的闪烁。
esbuild极速打包：React 19和TypeScript通过esbuild打包，速度远超传统打包工具。
零配置路由：文件系统即路由，无需手动编写路由配置文件。
📦 生产部署
当应用准备好上线时，Krock提供了一键式生产模式：
# Linux/MacDEPLOYMENT=prod python run.py# Windowsset DEPLOYMENT=prod python run.py
在生产模式下，框架会关闭热重载，通过esbuild压缩JavaScript和CSS，优化静态资源服务速度，为高流量场景做好充分准备。
💎 快速开始与总结
Krock为全栈Python开发者带来了：
Python后端 + React前端的完美融合：后端用Python处理业务逻辑，前端用React/TypeScript构建现代UI。
Next.js式的开发体验：文件系统路由、热重载、布局系统，但后端是纯Python。
数据库开箱即用：SQLAlchemy + Alembic预配置，支持SQLite、PostgreSQL、MySQL。
极低的启动门槛：一条命令创建项目，两条命令启动开发服务器。
开始你的Krock之旅，只需这几步：
# 创建新项目npx create-krock-app@latest# 进入项目目录cd 你的项目名# 安装Node.js依赖npm install# 安装Python依赖pip install -r requirements.txt# 启动开发服务器npm run dev
然后在浏览器中打开http://localhost:3000，你的第一个Krock全栈应用就已经在运行了。在pages/下创建.tsx文件构建页面，在pages/api/下创建.py文件编写后端逻辑，整个框架会为你自动处理好剩下的一切。
编辑：余文彬
审校：余雨馨
10个月宝宝每天需要喝多少奶粉？
