Topcoat
面向 Rust 的全能全栈框架
[][crates-url]
[][docs-url]
[][mit-url]
[][actions-url]
[][discord-url]
Topcoat 是一个模块化、开箱即用的 Rust 框架，用于构建全栈应用。它优先考虑简洁性和生产力。请参阅[入门指南](https://github.com/tokio-rs/topcoat/blob/main/crates/topcoat/docs/getting_started.md)来设置一个新项目。
```
use topcoat::{
Result,
router::{Router, RouterBuilderDiscoverExt, page},
view::{component, view},
};
#[tokio::main]
async fn main() {
topcoat::start(Router::builder().discover().build()).await.unwrap();
}
#[page("/")]
async fn home() -> Result {
view! {
hello(name: "World")
}
}
#[component]
async fn hello(name: &str) -> Result {
view! {
"Hello, " (name) "!" }
}
```
## Topcoat 的与众不同之处
### 无需样板代码的客户端响应式
Topcoat 在服务器上渲染所有标记：组件可以是异步的，并直接查询数据库，从而消除了传统上为单独的 API 层所需的所有样板代码。不过，交互性不必以一次网络往返为代价。`$(...)` 表达式是经过类型检查的普通 Rust 代码，Topcoat 会在服务器上对其进行初始渲染评估，并将其转换为 JavaScript，因此它可以在浏览器中立即重新运行。没有 wasm 包，也没有客户端构建步骤：
```
view! {
signal open = false;
// Runs entirely in the browser; no server round-trip.
"What is Topcoat?"
"A fullstack Rust framework."
}
```
当更新确实需要服务器时（例如获取最新的搜索结果），可以将组件标记为 `#[shard]`。Topcoat 会在其任意 `$(...)` 参数发生变化时在服务器上重新渲染该组件，并原位替换为新的 HTML：
```
#[component]
async fn search() -> Result {
view! {
signal query = String::new();
// Updates as the user types.
search_results(query: $(query.get()))
}
}
#[shard]
async fn search_results(cx: &Cx, query: String) -> Result {
view! {
// Your own server-side code, like a database query:
for product in search_products(cx, &query).await? {
(product.name)
}
}
}
```
### 强大且符合直觉的 HTML 模板
`view!` 宏忠于 HTML 和 Rust 的原生语法。你可以将熟悉的 Rust 控制流作为模板的一部分使用：
```
view! {
for item in nav_items {
(item.label)
}
}
```
使用 `topcoat fmt` CLI 命令可以自动格式化代码库中的 `view!` 片段（以及其他宏）。
### 基于模块的路由
Topcoat 可以选择从应用的模块结构中推断路由树（无需构建步骤）：
```
src/
|-- app.rs -> / (and the root layout)
`-- app/
|-- about.rs -> /about
|-- _marketing.rs (layout, no URL segment)
|-- _marketing/
| `-- pricing.rs -> /pricing
|-- posts.rs -> /posts
|-- posts/
| `-- id.rs -> /posts/{post_id}
`-- api/
`-- health.rs -> GET /api/health
```
### 资源打包
打包器会扫描编译后的二进制文件以查找 `asset!` 调用，将每个文件复制（甚至下载）到本地的资源目录中，并允许 Topcoat 通过激进的浏览器缓存来高效地提供这些资源。
```
const FERRIS: Asset = asset!("./ferris.png");
view! {
}
```
Topcoat 还内置了用于网络字体和图标的实用工具，并提供了与 [Fontsource](https://fontsource.org/)（Google Fonts）和 [Iconify](https://icon-sets.iconify.design/) 的便捷集成。
### 内置 Tailwind 支持
启用 `tailwind` feature，即可轻松将 Tailwind 集成到你的项目中：
```
view! {
}
```
## 学习 Topcoat
**从这里开始**
- [入门指南](https://github.com/tokio-rs/topcoat/blob/main/crates/topcoat/docs/getting_started.md)：创建新项目，安装 CLI，运行开发服务器。
- [源代码格式化](https://github.com/tokio-rs/topcoat/blob/main/crates/topcoat-cli/docs/fmt.md)：用于宏体的 `topcoat fmt`。
**渲染**
- [`view!` 宏](https://docs.rs/topcoat/latest/topcoat/view/macro.view.html)：模板语法、控制流、条件属性。
- [`#[component]` 宏](https://docs.rs/topcoat/latest/topcoat/view/attr.component.html)：将异步函数作为组件使用，并支持子内容。
- [`attributes!` 宏](https://docs.rs/topcoat/latest/topcoat/view/macro.attributes.html)：可复用的运行时属性片段。
- [`class!` 宏](https://docs.rs/topcoat/latest/topcoat/view/macro.class.html)：从静态和条件条目中生成以空格分隔的类列表。
**路由**
- [Router](https://docs.rs/topcoat/latest/topcoat/router/index.html)：页面、布局和 API 路由；支持手动配置和自动发现。
- [基于模块的路由](https://docs.rs/topcoat/latest/topcoat/router/macro.module_router.html)：从你的模块树中派生路由表。
**处理请求**
- [请求上下文 (`Cx`)](https://docs.rs/topcoat/latest/topcoat/context/index.html))：页面、布局和组件读取的值。
- [App 上下文](https://github.com/tokio-rs/topcoat/blob/main/crates/topcoat/docs/app_context.md)：跨请求共享长效值，按类型进行索引。
- [记忆化](https://docs.rs/topcoat/latest/topcoat/context/attr.memoize.html)：使用 `#[memoize]` 进行请求内缓存和扇出去重。
- [使用函数，而非 middleware](https://docs.rs/topcoat/latest/topcoat/context/index.html#functions-not-middlewares)：用于建模身份验证和其他请求作用域关注点的推荐方式。
- [Cookies](https://docs.rs/topcoat/latest/topcoat/cookie/index.html)：读写请求的 cookie 存储，支持签名、加密和带前缀的 cookie。
- [Sessions](https://docs.rs/topcoat/latest/topcoat/session/index.html)：自带存储的会话身份验证：登录/登出生命周期、滑动过期和 token 轮换。
**资源系统**
- [Assets](https://docs.rs/topcoat/latest/topcoat/asset/index.html)：在 Rust 中声明资源，并使用带有内容哈希的 URL 提供服务。
- [字体](https://docs.rs/topcoat/latest/topcoat/font/index.html)：打包并提供网络字体。
- [图标](https://docs.rs/topcoat/latest/topcoat/icon/index.html)：下载 Iconify 图标集或声明你自己的图标集。
**客户端响应式**
- [运行时](https://docs.rs/topcoat/latest/topcoat/runtime/index.html)：signals、`$(...)` 表达式、`@` 事件处理程序和 `:` 绑定属性。
- [表达式](https://docs.rs/topcoat/latest/topcoat/runtime/macro.expr.html)：双重 Rust/JavaScript 表达式语言及其词汇表。
- [过程](https://docs.rs/topcoat/latest/topcoat/runtime/attr.procedure.html)：可从浏览器调用的异步服务器函数。
- [Shards](https://docs.rs/topcoat/latest/topcoat/runtime/attr.shard.html)：当参数发生变化时在服务器上重新渲染的组件。
**第三方集成**
- [Tailwind](https://docs.rs/topcoat/latest/topcoat/tailwind/index.html)：无需 Node 的 Tailwind CSS，直接接入资源 pipeline。
- [htmx](https://docs.rs/topcoat/latest/topcoat/htmx/index.html)：借助请求/响应头辅助工具，从服务器驱动局部 HTML 替换。
**UI 组件**
- [Topcoat UI](https://github.com/tokio-rs/topcoat/blob/main/crates/topcoat/docs/ui.md)：通过 `topcoat ui add` 将预构建、可主题化的组件引入你的项目。