Phoenix-rs

Phoenix-rs 是由 极数本源（ApiZero） 打造的 Rust 全栈 Web 框架：以 Hyper 为 HTTP 核心，提供接近 Laravel 的开发体验，并默认集成 React + TypeScript（Islands / SPA / SSR）。一套约定，从路由、契约到前端 action 全链路类型安全。

源码镜像

克隆任选其一即可：

git clone https://github.com/MageGojo/Phoenix-rs.git
# 或
git clone https://gitcode.com/Roufsi/Phoenix-rs.git

AI / Agent 开发（默认必读）

凡在本仓库或基于 Phoenix-rs 的应用里写代码，AI 必须先加载官方 Skill，再动手。

Cursor 会从 .cursor/skills/phoenix/ 自动发现 Skill；其它 Agent 请按 AGENTS.md 用 Read 打开 SKILL.md。

特性一览

• Laravel 风格 DX：命名路由、Resource、中间件别名、px new / px make:* / px migrate / px dev / px release*
• 类型安全全链路：Rust Request / Resource / Page Props 契约自动生成 TypeScript 与可调用 action
• React 一等公民：Islands（默认）、SPA、SSR；页面协议局部导航；表单 / prefetch / partial reload
• 安全默认开启：Session、CSRF、CSP nonce、Host allowlist、限流、JWT + RBAC/ABAC；Argon2id 密码哈希（phoenix-crypto）
• 数据与运维：Toasty（SQLite / PostgreSQL / MySQL）+ 迁移、Prometheus 指标、可选 Redis / Queue / Mail / Storage
• 扩展与发版：编译期 Feature 插件；制品校验 + current 原子切换与回滚

快速开始

要求：Rust 1.95+、Node.js（Vite / React）、可选 SQLite（默认）/ PostgreSQL / MySQL。数据库驱动通过 Cargo feature 按需编译；新应用默认只链接 SQLite。

安装 px

从 crates.io 安装（推荐）：

cargo install px-cli

或从 Git 安装（镜像任选）：

cargo install --git https://github.com/MageGojo/Phoenix-rs px-cli
# 或
cargo install --git https://gitcode.com/Roufsi/Phoenix-rs px-cli

本仓库内开发时也可用 cargo install --path crates/phoenix-cli。

px-cli 是 crates.io 包名（安装后命令为 px）；安装后 PATH 里就是二进制 px。px new 生成的应用依赖 crates.io 上的门面包 phoenixrs（代码里仍写 use phoenix::…）。

创建并运行

px new my-app
cd my-app
cp .env.example .env   # 默认使用 SQLite，无需额外配置即可启动
px migrate
px dev

切换 PostgreSQL 或 MySQL 时，同时把应用 Cargo.toml 的默认 feature 与 config/database.toml 对齐；例如一次性 PostgreSQL 构建使用 cargo build --no-default-features --features pgsql。

启动成功后访问 **http://127.0.0.1:3000**。切换到 PostgreSQL / MySQL 见 docs/CONFIG.md。

生成完整 CRUD 骨架：

px make:model Post --all

运行官方示例

cd examples/blog
px migrate
px dev
# http://127.0.0.1:3000

blog 示例包含真实 Auth 链路：Toasty 持久化用户、Argon2id 密码哈希、Cookie Session 登录 / 登出与受保护的 /admin 后台（设计见 docs/AUTH_ADMIN.md）。

多应用挂载示例见 examples/multi-app；Feature 插件示例见 examples/plugin-greeter。

最小代码

use phoenix::prelude::*;

pub struct UserController;

impl UserController {
    pub async fn show(request: Request) -> Response {
        let user = request.param("user").unwrap_or("unknown");
        Json(json!({ "user": user })).into_response()
    }
}

Routes::new()
    .get("/users/{user}", UserController::show)
    .name("users.show");

import { members } from "../generated/routes.js";

const member = await members.store({ name });

更多：业务开发指南 · 开发者体验 · React 渲染

命名（crates.io / 托管）

仓库结构

.cursor/skills/phoenix/  # AI 官方 Skill（入库，默认先读）
AGENTS.md                # Agent 强制约定入口
crates/                  # Rust 框架组件与统一入口 phoenixrs（lib = phoenix）
packages/                # @apizero/react、@apizero/vite、SSR 包
schemas/                 # config/*.toml JSON Schema（Taplo）
examples/blog            # 参考应用
examples/multi-app
examples/plugin-greeter  # Feature 插件示例
fuzz/                    # cargo-fuzz 目标（HTTP / 密码学边界）
benchmarks/              # Criterion 基准
docs/                    # 产品、架构与领域文档
.github/workflows        # CI（GitHub Actions）

关于 fuzz/

fuzz/ 属于本框架质量门禁，不是无关目录。它使用 cargo-fuzz / libFuzzer，对 phoenix-http 边界与 phoenix-crypto 盲索引信封等做模糊测试。日常开发不必运行；CI / 安全流水线会做 smoke。产物目录（fuzz/target、artifacts、corpus 样本）已在 .gitignore 中排除。

开发与检查

cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo fmt --all -- --check
npm run ci:node

质量门禁说明见 docs/QUALITY_GATES.md。公开托管与 crates.io 发布规划见 docs/RELEASE.md。

文档索引

当前状态

早期开发阶段。crates.io 门面 phoenixrs 与 CLI px-cli 持续发版；GitHub / GitCode 双镜像同步。能力按 Cargo feature 按需编译（sqlite/tls/websocket/sse/auth/jwt/password/metrics 等，见 docs/FEATURES.md）。核心垂直切片（HTTP、路由、契约、React、安全、CLI、迁移）、TOML 配置、MySQL 驱动、Feature 插件与发版流水线 MVP 已可运行；blog 示例 Auth 为真实持久化链路（Toasty 用户 + Argon2id + Cookie Session，见 docs/AUTH_ADMIN.md）。仍在演进：邮件真实 SMTP、队列生产驱动、px make:auth 生成器、服务端 partial props 求值。

公司与许可

• 出品：极数本源（ApiZero）— https://apizero.cn/
• 联系：api@zerois.cn
• 源码：GitHub · GitCode
• 许可：MIT

© 2026 极数本源 ApiZero. All rights reserved.