axum-standards
Use when building an Axum (or Actix-web) async Rust web service in a touchstone repo — routing, extractors, Tower middleware, IntoResponse errors, state/DI, graceful shutdown. Triggers on `axum`/`actix-web` in Cargo.toml, `Router`/`async fn` HTTP handlers, `State`/`Json`/`Path` extractors. Rust-language rules (toolchain, clippy, thiserror, tokio depth) live in the rust skill.
- License 许可
- MIT
- 最近更新
- 2026-08-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- axum-standards
- license
- MIT
- metadata
- { "author": "touchstone", "version": "0.2.0" }
- description
- Use when building an Axum (or Actix-web) async Rust web service in a touchstone repo — routing, extractors, Tower middleware, IntoResponse errors, state/DI, graceful shutdown. Triggers on `axum`/`actix-web` in Cargo.toml, `Router`/`async fn` HTTP handlers, `State`/`Json`/`Path` extractors. Rust-language rules (toolchain, clippy, thiserror, tokio depth) live in the rust skill.
03 SKILL.md 正文
Axum (Rust Backend framework)
Full standard: standards/frameworks/axum.md (layers on standards/languages/rust.md). This
skill inlines the load-bearing rules so it stays useful when installed standalone in
~/.claude/skills/:
Always
- Axum 0.8 is the default (on Tokio/Tower/Hyper); Actix-web is the measured escape hatch. Path
syntax is
/{id}, not 0.7's/:id. - handler → service → repository layering; thin handlers delegate and return
Result<T, AppError>via?. Splitlibfrombin. State<AppState>is the DI container — cheap-Clone behindArc/pools, built once inmain, no static singletons; sub-states viaFromRef.- Typed extractors (
Path/Query/Json); at most one body extractor and it goes last; route rejections throughAppError. - Validate every boundary (
garde/validator) in a shared extractor before the service runs.
Don't get burned
- Errors: one
AppErrorimplementingIntoResponse(thiserror), maps source → status in one place → problem+json. Nounwrap()/expect()in handlers (see rust skill §4); never leak asqlx::Erroror stack trace to the client. - Middleware: compose with
ServiceBuilder— top-to-bottom = outermost-to-innermost.TraceLayeroutermost, then CORS (explicit allow-list, neverAnyin prod) + body-limit +TimeoutLayer, auth innermost. - Async: all rust-skill tokio rules apply — never block the executor, bound awaits with
tokio::time::timeout, make handler work cancel-safe (the client disconnecting drops the future). - Shutdown:
axum::serve(...).with_graceful_shutdown(signal)onSIGTERMand Ctrl-C; close the pool after drain; bound by the request timeout. - DB:
sqlxcompile-checked queries in the repository (SeaORM only at scale); migrations at deploy, not on first request.
Done
Handler → service → repo · typed extractors (body last) · one AppError: IntoResponse, no unwrap in handlers · ServiceBuilder ordering (Trace outer, auth inner) + explicit CORS · with_graceful_shutdown on SIGTERM+Ctrl-C · oneshot handler tests + Testcontainers for DB. See standards/frameworks/axum.md.
04 同仓库更多 Skills
ok-standards
Use when writing shell, per standards/languages/shell.md.
demo-standards
Use when editing demo code in a touchstone fixture repo, a deliberately ordinary description that is long enough to clear the forty character minimum.
demo-standards
Use when editing demo code in a touchstone fixture repo, a deliberately ordinary description that is long enough to clear the forty character minimum.
demo-standards
Use when editing demo code in a touchstone fixture repo, a deliberately ordinary description that is long enough to clear the forty character minimum.
demo-standards
Use when editing demo code in a touchstone fixture repo, a deliberately ordinary description that is long enough to clear the forty character minimum.
demo-standards
Use when editing demo code in a touchstone fixture repo, a deliberately ordinary description that is long enough to clear the forty character minimum.