# learn-rust **Repository Path**: cjl2385/learn-rust ## Basic Information - **Project Name**: learn-rust - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-15 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # learn-rust 写给前端开发者(TS / React / Vue / Hono / NestJS / Drizzle)的 Rust 课程,配一套可交互的 API 手册。和 learn-go 同构,读者默认已学完 learn-go ## 开始 ```bash cargo run -p lab # 默认仅监听 127.0.0.1:8082 cargo run -p lab -- --host 0.0.0.0 # 局域网访问:启动后复制控制台中的带 token 链接 LAB_ADDR=10.0.0.4:8082 cargo run -p lab # 兼容旧方式;非本机绑定也会自动要求 token # 或 cargo run -p lab -- --addr 10.0.0.4:8082 ``` 整个项目只需要启动这一个服务,不用另开静态服务器。lab 同时托管页面和演示接口。页面里的演示会请求 Rust 后端,看到的是真实运行结果;练习区可以改代码后直接运行或检查。直接双击 HTML 也能读,演示区显示快照 首次构建要下载并编译依赖:本机(M4,依赖已在 cargo 缓存里)约 10 秒,从零下载取决于网络。服务启动后立即可以访问页面,后台还会预热 `/api/run` 用的预装依赖(约 5 到 15 秒,日志里出现 `playground ready` 表示完成)。预热期间 `/api/run` 返回 `lab: warming up`,页面显示这条提示,稍后重试即可 ## 目录 ``` learn-rust/ ├── index.html # 导航:课程 / API 手册 / 附录 ├── Cargo.toml # workspace:统一依赖版本与 lint ├── rust-toolchain.toml # 固定 1.99.1,诊断快照依赖这个版本 ├── lab/ # 本地服务:静态页面 + /api/... 演示接口 + /api/run ├── crates/labkit/ # 演示接口的公共约定:信封、错误约定、快照校验 ├── crates/playrun/ # /api/run 的实现:预热、直接调用 rustc、脱敏 ├── playground/ # /api/run 预装依赖的清单(空 crate) ├── lessons/ # 课程,每课一个 crate:源稿、HTML、示例、练习、测试、演示接口 ├── reference/ # API 手册,每本一个 crate ├── appendix/ # 附录,每篇一个 crate ├── scripts/ # check-docs.ts:源稿检查 └── STYLE.md # 写作与制作规范(含并行写作的开工清单) ``` 课程地图见 `STYLE.md` 第 10 节 ## 环境 - 通过 rustup 安装 Rust,`rust-toolchain.toml` 会自动选择 1.99.1,含 clippy 与 rustfmt。设置了环境变量 `RUSTUP_TOOLCHAIN` 时它优先,需要和 1.99.1 一致 - Miri 是可选的:`rustup +nightly component add miri` 之后,`/api/run` 的 `miri` 模式可用,没装时该模式返回明确的错误 - 重新渲染页面需要 bun 和 answer-with-html skill,步骤见 `STYLE.md` 第 9 节 - 常用检查:`bun run check`(格式与 Clippy)、`bun run test`(workspace 测试)、`bun run check-docs`(文档检查);也可以直接使用 Cargo 命令 ## 关于 /api/run `/api/run` 会在本机编译并运行提交的 Rust 代码,只用于本地学习,**不是沙箱**。lab 默认只监听 127.0.0.1。显式用 `--host`、`--addr` 或 `LAB_ADDR` 绑定非本机地址时,lab 会生成随机访问 token,控制台打印可复制的 URL;首次访问换为 HttpOnly、SameSite=Strict cookie,页面与 API 都需要授权。服务校验 Host 防 DNS 重绑定、拒绝跨 Origin,并要求 POST 使用 JSON。所有 `/api/` 请求若带 `Sec-Fetch-Site`,只允许 `same-origin`,拒绝跨站、同站非同源等浏览器请求;未带该 header 的命令行客户端兼容通过。HTTP 没有加密,token 可能被同网络监听者窃取;只在可信网络(如自己的 WireGuard)里开放,不要转发到公网。持有 token 的用户仍可执行任意代码 具体做了什么限制,以及没有做什么: - 每个请求在独立临时目录里直接调用 `rustc`,不允许提交 `Cargo.toml` 与 `build.rs`,只能链接 `playground/Cargo.toml` 里预装的依赖 - 总时限 20 秒(编译加运行),超时杀掉整个进程组;stdout 与 stderr 各保留 64 KiB;同时最多 3 个请求,其余排队;代码最大 64 KiB - 运行读者程序时清空环境变量,只留 `PATH` 与 `LANG`,stdin 是空 - 输出里的临时目录、sysroot、`~/.cargo`、用户目录都会换成占位符 - 没有限制:文件系统、网络、内存、CPU 之外的资源。提交的程序拥有当前用户的全部权限 - **过程宏在编译期就会执行代码**,所以 `check`、`clippy` 模式同样危险:`/api/run` 的任何模式都能在编译阶段运行任意代码,不要因为「只是检查」就放宽监听范围 - 静态文件服务拒绝点文件、点目录和 `target/`,其余仓库内容(包括 `.rs` 源码)都可以读取