vespera

分类: 开发与编程 | 上传者: dev-five-git | 下载: 0 | 版本: v1.0（最新）

使用 Vespera 构建 API - 适用于 Rust/Axum 的类似 FastAPI 的 DX。涵盖路由处理程序、模式派生和 OpenAPI 生成。

更新日志: Source: GitHub https://github.com/dev-five-git/vespera

目录结构

当前层级: tree/main/

📁 .changepacks/
- 📄 config.json 279 B
📁 .github/
- 📁 workflows/
  - 📄 CI.yml 3.2 KB
- 📄 FUNDING.yml 41 B
📁 crates/
- 📁 vespera/
  - 📁 src/
    
    📄 lib.rs 4.5 KB
    
    📄 multipart.rs 26.2 KB
  - 📄 Cargo.toml 1.0 KB
- 📁 vespera_core/
  - 📁 src/
    
    📄 lib.rs 233 B
    
    📄 openapi.rs 14.6 KB
    
    📄 route.rs 15.2 KB
    
    📄 schema.rs 16.8 KB
  - 📄 Cargo.toml 335 B
- 📁 vespera_inprocess/
  - 📁 src/
    
    📄 lib.rs 7.2 KB
  - 📄 Cargo.toml 491 B
- 📁 vespera_jni/
  - 📁 src/
    
    📄 lib.rs 2.5 KB
  - 📄 Cargo.toml 361 B
- 📁 vespera_macro/
  - 📁 src/
    
    📁 parser/
    
    📁 schema/
    
    📁 snapshots/
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__adjacently_tagged_snapshot@adjacently_tagged.snap 31.5 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__externally_tagged_empty_struct_variant@externally_tagged_empty_struct.snap 12.4 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__internally_tagged_skips_tuple_variant@internally_tagged_skip_tuple.snap 11.7 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__internally_tagged_snapshot@internally_tagged.snap 23.1 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__untagged_multi_field_tuple_variant@untagged_multi_field_tuple.snap 17.4 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__enum_repr_tests__untagged_snapshot@untagged.snap 13.5 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_named_object.snap 11.4 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_tuple_multi.snap 11.3 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_tuple_single.snap 5.0 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_unit_variants@unit_simple.snap 1.0 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_unit_variants@unit_simple_snake.snap 1.0 KB
    
    📄 vespera_macro__parser__schema__enum_schema__tests__parse_enum_to_schema_unit_variants@unit_status.snap 1.0 KB
    
    📄 enum_schema.rs 61.9 KB
    
    📄 generics.rs 10.6 KB
    
    📄 mod.rs 1.8 KB
    
    📄 serde_attrs.rs 83.9 KB
    
    📄 struct_schema.rs 16.2 KB
    
    📄 type_schema.rs 61.3 KB
    
    📁 snapshots/
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_form_body.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_header_custom.snap 1.8 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_header_value_and_arg.snap 1.8 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_json_body.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_method_receiver.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_path_single.snap 1.9 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_path_tuple.snap 3.7 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_path_tuple_destructure.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_query_hashmap.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_query_map.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_query_struct.snap 3.8 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_query_unknown.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_query_user.snap 3.6 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_raw_multipart_body.snap 88 B
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_typed_header_and_arg.snap 1.8 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_typed_header_multi.snap 5.4 KB
    
    📄 vespera_macro__parser__parameters__tests__parse_function_parameter_cases@params_typed_multipart_body.snap 88 B
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_form.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_i32.snap 86 B
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_json.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_multipart_raw.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_self_ref.snap 86 B
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_str.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_string.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_typed_multipart.snap 2.3 KB
    
    📄 vespera_macro__parser__request_body__tests__parse_request_body_cases@req_body_vec_string.snap 86 B
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_named_object.snap 11.0 KB
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_tuple_multi.snap 10.9 KB
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_tuple_and_named_variants@tuple_named_tuple_single.snap 4.8 KB
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_unit_variants@unit_simple.snap 1011 B
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_unit_variants@unit_simple_snake.snap 1021 B
    
    📄 vespera_macro__parser__schema__tests__parse_enum_to_schema_unit_variants@unit_status.snap 1019 B
    
    📄 AGENTS.md 2.6 KB
    
    📄 is_keyword_type.rs 1.7 KB
    
    📄 mod.rs 401 B
    
    📄 operation.rs 24.8 KB
    
    📄 parameters.rs 47.4 KB
    
    📄 path.rs 1.0 KB
    
    📄 request_body.rs 7.9 KB
    
    📄 response.rs 30.3 KB
    
    📁 route/
    
    📄 mod.rs 30 B
    
    📄 utils.rs 19.4 KB
    
    📁 schema_macro/
    
    📄 circular.rs 35.7 KB
    
    📄 codegen.rs 15.9 KB
    
    📄 file_cache.rs 21.5 KB
    
    📄 file_lookup.rs 57.8 KB
    
    📄 from_model.rs 91.2 KB
    
    📄 inline_types.rs 42.2 KB
    
    📄 input.rs 27.8 KB
    
    📄 mod.rs 32.8 KB
    
    📄 seaorm.rs 46.7 KB
    
    📄 tests.rs 69.2 KB
    
    📄 transformation.rs 13.3 KB
    
    📄 type_utils.rs 23.7 KB
    
    📄 validation.rs 10.2 KB
    
    📄 args.rs 11.1 KB
    
    📄 collector.rs 34.4 KB
    
    📄 cron_impl.rs 7.5 KB
    
    📄 error.rs 1.2 KB
    
    📄 file_utils.rs 8.2 KB
    
    📄 http.rs 2.2 KB
    
    📄 lib.rs 12.3 KB
    
    📄 metadata.rs 9.1 KB
    
    📄 method.rs 3.1 KB
    
    📄 multipart_impl.rs 40.3 KB
    
    📄 openapi_generator.rs 66.3 KB
    
    📄 route_impl.rs 13.4 KB
    
    📄 router_codegen.rs 65.4 KB
    
    📄 schema_impl.rs 20.7 KB
    
    📄 vespera_impl.rs 67.9 KB
  - 📄 AGENTS.md 2.4 KB
  - 📄 Cargo.toml 610 B
📁 examples/
- 📁 axum-example/
  - 📁 models/
    
    📄 config.vespertide.json 441 B
    
    📄 memo.vespertide.json 997 B
    
    📄 memo_comment.vespertide.json 923 B
    
    📄 single.json 299 B
    
    📄 single_rel.json 434 B
    
    📄 user.vespertide.json 775 B
    
    📄 uuid_item.vespertide.json 667 B
  - 📁 src/
    
    📁 cron/
    
    📄 cleanup.rs 321 B
    
    📄 mod.rs 17 B
    
    📁 models/
    
    📄 config.rs 386 B
    
    📄 memo.rs 1.3 KB
    
    📄 memo_comment.rs 927 B
    
    📄 mod.rs 121 B
    
    📄 single.rs 437 B
    
    📄 single_rel.rs 475 B
    
    📄 user.rs 899 B
    
    📄 uuid_item.rs 643 B
    
    📁 routes/
    
    📁 foo/
    
    📄 mod.rs 1.3 KB
    
    📁 path/
    
    📁 prefix/
    
    📄 mod.rs 178 B
    
    📄 mod.rs 942 B
    
    📄 config.rs 2.4 KB
    
    📄 enums.rs 3.4 KB
    
    📄 error.rs 2.9 KB
    
    📄 flatten.rs 4.2 KB
    
    📄 form.rs 2.0 KB
    
    📄 generic.rs 2.6 KB
    
    📄 health.rs 74 B
    
    📄 memos.rs 4.4 KB
    
    📄 mod.rs 5.9 KB
    
    📄 typed_form.rs 4.9 KB
    
    📄 typed_header.rs 611 B
    
    📄 users.rs 7.0 KB
    
    📄 uuid_items.rs 1.1 KB
    
    📄 lib.rs 1.5 KB
    
    📄 main.rs 367 B
  - 📁 tests/
    
    📁 snapshots/
    
    📄 integration_test__openapi.snap 98.6 KB
    
    📄 integration_test.rs 58.9 KB
  - 📄 Cargo.lock 38.7 KB
  - 📄 Cargo.toml 665 B
  - 📄 openapi.json 98.5 KB
  - 📄 vespertide.json 401 B
- 📁 rust-jni-demo/
  - 📁 java/
    
    📁 demo-app/
    
    📁 src/
    
    📁 main/
    
    📁 java/
    
    📁 kr/
    
    📁 go/
    
    📁 demo/
    
    📄 DemoApplication.java 541 B
    
    📁 resources/
    
    📄 application.yml 105 B
    
    📄 build.gradle.kts 2.4 KB
    
    📁 gradle/
    
    📁 wrapper/
    
    📄 gradle-wrapper.jar 44.6 KB
    
    📄 gradle-wrapper.properties 253 B
    
    📄 build.gradle.kts 296 B
    
    📄 gradle.properties 25 B
    
    📄 gradlew 8.4 KB
    
    📄 gradlew.bat 2.7 KB
    
    📄 settings.gradle.kts 59 B
  - 📁 src/
    
    📁 routes/
    
    📄 documents.rs 8.4 KB
    
    📄 health.rs 131 B
    
    📄 mod.rs 35 B
    
    📄 lib.rs 9.9 KB
    
    📄 main.rs 807 B
  - 📄 Cargo.lock 35.3 KB
  - 📄 Cargo.toml 490 B
  - 📄 README.md 4.7 KB
- 📁 third/
  - 📁 src/
    
    📁 routes/
    
    📄 mod.rs 993 B
    
    📄 lib.rs 306 B
  - 📄 Cargo.lock 38.7 KB
  - 📄 Cargo.toml 370 B
📁 libs/
- 📁 vespera-bridge/
  - 📁 gradle/
    
    📁 wrapper/
    
    📄 gradle-wrapper.jar 42.6 KB
    
    📄 gradle-wrapper.properties 252 B
  - 📁 src/
    
    📁 main/
    
    📁 java/
    
    📁 com/
    
    📁 devfive/
    
    📁 vespera/
    
    📁 bridge/
    
    📄 VesperaBridge.java 3.0 KB
    
    📄 VesperaProxyController.java 3.3 KB
  - 📄 build.gradle.kts 2.3 KB
  - 📄 gradlew 8.6 KB
  - 📄 gradlew.bat 2.8 KB
  - 📄 settings.gradle.kts 135 B
📄 .gitignore 202 B
📄 AGENTS.md 9.6 KB
📄 Cargo.lock 104.5 KB
📄 Cargo.toml 1.1 KB
📄 openapi.json 98.5 KB
📄 README.md 19.8 KB
📄 SKILL.md 18.3 KB

SKILL.md

---
name: vespera
description: Build APIs with Vespera - FastAPI-like DX for Rust/Axum. Covers route handlers, Schema derivation, and OpenAPI generation.
---

# Vespera Usage Guide

Vespera = FastAPI DX for Rust. Zero-config OpenAPI 3.1 generation via compile-time macro scanning.

## Quick Start

```rust
// 1. Main entry - vespera! macro handles everything
let app = vespera!(
    openapi = "openapi.json",  // writes file at compile time
    title = "My API",
    version = "1.0.0",
    docs_url = "/docs",        // Swagger UI
    redoc_url = "/redoc"       // ReDoc alternative
);

// 2. Route handlers - MUST be pub async fn
#[vespera::route(get, path = "/{id}", tags = ["users"])]
pub async fn get_user(Path(id): Path<u32>) -> Json<User> { ... }

// 3. Custom types - derive Schema for OpenAPI inclusion
#[derive(Serialize, Deserialize, vespera::Schema)]
pub struct User { id: u32, name: String }
```

---

## Type Mapping Reference

| Rust Type | OpenAPI Schema | Notes |
|-----------|----------------|-------|
| `String`, `&str` | `string` | |
| `i8`-`i128`, `u8`-`u128` | `integer` | |
| `f32`, `f64` | `number` | |
| `bool` | `boolean` | |
| `Vec<T>` | `array` + items | |
| `BTreeSet<T>`, `HashSet<T>` | `array` + items + `uniqueItems: true` | Set types |
| `Option<T>` | T (nullable context) | Parent marks as optional |
| `HashMap<K,V>` | `object` + additionalProperties | |
| `Uuid` | `string` + `format: uuid` | |
| `Decimal` | `string` + `format: decimal` | |
| `NaiveDate` | `string` + `format: date` | |
| `NaiveTime` | `string` + `format: time` | |
| `DateTime`, `DateTimeWithTimeZone` | `string` + `format: date-time` | |
| `FieldData<NamedTempFile>` | `string` + `format: binary` | File upload field |
| `()` | empty response | 204 No Content |
| Custom struct | `$ref` | Must derive Schema |

## Extractor Mapping Reference

| Axum Extractor | OpenAPI Location | Notes |
|----------------|------------------|-------|
| `Path<T>` | path parameter | T can be tuple or struct |
| `Query<T>` | query parameters | Struct fields become params |
| `Json<T>` | requestBody | application/json |
| `Form<T>` | requestBody | application/x-www-form-urlencoded |
| `TypedMultipart<T>` | requestBody | multipart/form-data — typed with schema |
| `Multipart` | requestBody | multipart/form-data — untyped, generic object |
| `State<T>` | **ignored** | Internal, not API |
| `Extension<T>` | **ignored** | Internal, not API |
| `TypedHeader<T>` | header parameter | |
| `HeaderMap` | **ignored** | Too dynamic |

---

## Route Handler Requirements

```rust
// ❌ Private function - NOT discovered
async fn get_users() -> Json<Vec<User>> { ... }

// ❌ Non-async function - NOT supported
pub fn get_users() -> Json<Vec<User>> { ... }

// ✅ Must be pub async fn
pub async fn get_users() -> Json<Vec<User>> { ... }
```

---

## File Structure → URL Mapping

```
src/routes/
├── mod.rs           → /              (root routes)
├── users.rs         → /users
├── posts.rs         → /posts
└── admin/
    ├── mod.rs       → /admin
    └── stats.rs     → /admin/stats
```

Handler path is: `{file_path} + {#[route] path}`

```rust
// In src/routes/users.rs
#[vespera::route(get, path = "/{id}")]
pub async fn get_user(...) // → GET /users/{id}
```

---

## Serde Integration

Vespera respects serde attributes:

```rust
#[derive(Serialize, Deserialize, Schema)]
#[serde(rename_all = "camelCase")]  // ✅ Respected in schema
pub struct UserResponse {
    user_id: u32,        // → "userId" in JSON Schema
    
    #[serde(rename = "fullName")]  // ✅ Respected
    name: String,        // → "fullName" in JSON Schema
    
    #[serde(default)]    // ✅ Recognized (does NOT affect `required` — only Option<T> does)
    bio: Option<String>,
    
    #[serde(skip)]       // ✅ Excluded from schema
    internal_id: u64,
}
```

---

## Debugging Tips

### Schema Not Appearing

1. Check `#[derive(Schema)]` on the type
2. Check type is used in a route handler's input/output
3. Check for generic types - all type params need Schema

```rust
// Generic types need Schema on all params
#[derive(Schema)]
struct Paginated<T: Schema> {  // T must also derive Schema
    items: Vec<T>,
    total: u32,
}
```

### Macro Expansion

```bash
# See what vespera! generates
cargo expand

# Validate OpenAPI output
npx @apidevtools/swagger-cli validate openapi.json
```

---

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `VESPERA_DIR` | Route folder name | `routes` |
| `VESPERA_OPENAPI` | OpenAPI output path | none |
| `VESPERA_TITLE` | API title | `API` |
| `VESPERA_VERSION` | API version | `CARGO_PKG_VERSION` |
| `VESPERA_DOCS_URL` | Swagger UI path | none |
| `VESPERA_REDOC_URL` | ReDoc path | none |
| `VESPERA_SERVER_URL` | Server URL | `http://localhost:3000` |

---

## schema_type! Macro (RECOMMENDED)

> **ALWAYS prefer `schema_type!` over manually defining request/response structs.**
> 
> Benefits:
> - Single source of truth (your model)
> - Auto-generated `From` impl for easy conversion
> - Automatic type resolution (enums, custom types → absolute paths)
> - SeaORM relation support (HasOne, BelongsTo, HasMany)
> - No manual field synchronization

### Best Practices

| DO | DON'T |
|----|-------|
| Use `pick` to select only needed fields | Define manual structs that duplicate Model fields |
| Use `omit` to exclude sensitive fields | Use `name` parameter unnecessarily |
| Use full `crate::models::...` paths | Rely on implicit module resolution |
| Define schema near route handlers | Scatter schemas across unrelated files |

**Primary Parameters (USE THESE):**
- `pick = [...]` - Allowlist: include ONLY these fields
- `omit = [...]` - Denylist: exclude these fields
- `omit_default` - Auto-omit fields with DB defaults (primary_key, default_value)

**Advanced Parameters (USE SPARINGLY):**
- `partial` - For PATCH endpoints only
- `rename` - Only when API naming differs from model
- `add` - Only when truly new fields needed (breaks `From` impl)
- `name` - **AVOID** unless same-file Model reference (see below)

### Why Not Manual Structs?

```rust
// ❌ BAD: Manual struct definition - requires sync with Model
#[derive(Serialize, Deserialize, Schema)]
pub struct UserResponse {
    pub id: i32,
    pub name: String,
    pub email: String,
    // Forgot to add new field? Schema out of sync!
}

// ✅ GOOD: Derive from Model - always in sync
schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]);
```

### Basic Syntax

```rust
// Pick specific fields
schema_type!(CreateUserRequest from crate::models::user::Model, pick = ["name", "email"]);

// Omit specific fields
schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash", "internal_id"]);

// Add new fields (NOTE: no From impl generated when using add)
schema_type!(UpdateUserRequest from crate::models::user::Model, pick = ["name"], add = [("id": i32)]);

// Rename fields
schema_type!(UserDTO from crate::models::user::Model, rename = [("id", "user_id")]);

// Partial updates (all fields become Option<T>)
schema_type!(UserPatch from crate::models::user::Model, partial);

// Partial updates (specific fields only)
schema_type!(UserPatch from crate::models::user::Model, partial = ["name", "email"]);

// Auto-omit fields with DB defaults (primary_key, default_value = "...")
schema_type!(CreatePostRequest from crate::models::post::Model, omit_default);

// Combine omit_default with add
schema_type!(CreateItemRequest from crate::models::item::Model, omit_default, add = [("tags": Vec<String>)]);

// Custom serde rename strategy
schema_type!(UserSnakeCase from crate::models::user::Model, rename_all = "snake_case");

// Custom OpenAPI schema name
schema_type!(Schema from Model, name = "UserSchema");

// Skip Schema derive (won't appear in OpenAPI)
schema_type!(InternalDTO from Model, ignore);

// Disable Clone derive
schema_type!(LargeResponse from SomeType, clone = false);
```

### Same-File Model Reference (When to Use `name`)

> **The `name` parameter is ONLY needed for same-file Model references.**
> For cross-file references, use full paths and descriptive struct names instead.

When defining Schema in the same file as Model (common for SeaORM entities):

```rust
// In src/models/user.rs
pub struct Model {
    pub id: i32,
    pub name: String,
    pub status: UserStatus,  // Custom enum - auto-resolved to absolute path
}

pub enum UserStatus { Active, Inactive }

// ✅ CORRECT: Same-file reference - use `name` for OpenAPI schema name
vespera::schema_type!(Schema from Model, name = "UserSchema");

// ❌ WRONG: Using `name` for cross-file reference
// schema_type!(Schema from crate::models::user::Model, name = "UserResponse");
// ✅ CORRECT: Use descriptive struct name instead
// schema_type!(UserResponse from crate::models::user::Model, omit = ["password"]);
```

**Why avoid `name` for cross-file references?**
- The struct name itself becomes the OpenAPI schema name
- `UserResponse` is clearer than `Schema` with `name = "UserResponse"`
- Less parameters = less complexity

### Cross-File References

Reference structs from other files using full module paths:

```rust
// In src/routes/users.rs
use vespera::schema_type;

// Reference model from src/models/user.rs
schema_type!(CreateUserRequest from crate::models::user::Model, pick = ["name", "email"]);
```

The macro reads the source file at compile time - no special annotations needed on the source struct.

### Auto-Generated From Impl

When `add` is NOT used, `schema_type!` generates a `From` impl for easy conversion:

```rust
// This:
schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]);

// Generates:
pub struct UserResponse { id, name, email, created_at }

impl From<crate::models::user::Model> for UserResponse {
    fn from(source: crate::models::user::Model) -> Self {
        Self { id: source.id, name: source.name, ... }
    }
}

// Usage:
let model: Model = db.find_user(id).await?;
Json(model.into())  // Easy conversion!
```

**Note:** `From` is NOT generated when `add` is used (can't auto-populate added fields).

### Parameters

**Recommended (Primary):**

| Parameter | Description | Example |
|-----------|-------------|---------|
| `pick` | Include only these fields | `pick = ["name", "email"]` |
| `omit` | Exclude these fields | `omit = ["password"]` |
| `omit_default` | Auto-omit fields with DB defaults | `omit_default` (bare keyword) |

**Situational (Use When Needed):**

| Parameter | Description | When to Use |
|-----------|-------------|-------------|
| `partial` | Make fields optional | PATCH endpoints only |
| `rename` | Rename fields | API naming differs from model |
| `rename_all` | Serde rename strategy | Different casing needed |
| `add` | Add new fields | New fields not in model (breaks `From` impl) |
| `multipart` | Derive `Multipart` | Multipart form-data endpoints |

**Avoid (Special Cases Only):**

| Parameter | Description | When to Use |
|-----------|-------------|-------------|
| `name` | Custom OpenAPI schema name | **Same-file Model reference only** |
| `ignore` | Skip Schema derive | Internal DTOs not for OpenAPI |
| `clone` | Control Clone derive | Large structs where Clone is expensive |

### SeaORM Integration (RECOMMENDED)

`schema_type!` has first-class SeaORM support with automatic relation handling:

```rust
// src/models/memo.rs
#[derive(Clone, Debug, DeriveEntityModel)]
#[sea_orm(table_name = "memo")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub title: String,
    pub user_id: i32,
    pub status: MemoStatus,                      // Custom enum
    pub user: BelongsTo<super::user::Entity>,    // → Option<Box<UserSchema>>
    pub comments: HasMany<super::comment::Entity>, // → Vec<CommentSchema>
    pub created_at: DateTimeWithTimeZone,        // → chrono::DateTime<FixedOffset>
}

#[derive(EnumIter, DeriveActiveEnum, Serialize, Deserialize, Schema)]
pub enum MemoStatus { Draft, Published, Archived }

// Generates Schema with proper types - no imports needed!
vespera::schema_type!(Schema from Model, name = "MemoSchema");
```

**Automatic Type Conversions:**

| SeaORM Type | Generated Type | Notes |
|-------------|---------------|-------|
| `HasOne<Entity>` | `Box<Schema>` or `Option<Box<Schema>>` | Based on FK nullability |
| `BelongsTo<Entity>` | `Option<Box<Schema>>` | Always optional |
| `HasMany<Entity>` | `Vec<Schema>` | |
| `DateTimeWithTimeZone` | `vespera::chrono::DateTime<FixedOffset>` | No SeaORM import needed |
| Custom enums | `crate::module::EnumName` | Auto-resolved to absolute path |

**Circular Reference Handling:** Automatically detected and handled by inlining fields.

**Database Defaults in OpenAPI:** Fields with `#[sea_orm(default_value = "...")]` or `#[sea_orm(primary_key)]` automatically get `default` values in the generated OpenAPI schema. SQL functions like `NOW()` and `gen_random_uuid()` are mapped to type-appropriate defaults.

**Required Logic:** `required` is determined **solely by nullability** (`Option<T>`). Fields with `#[serde(default)]` or `#[serde(skip_serializing_if)]` are still `required` unless they are `Option<T>`.

### Complete Example

```rust
// ============================================
// src/models/user.rs (SeaORM entity)
// ============================================
#[derive(Clone, Debug, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "users")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    pub email: String,
    pub status: UserStatus,
    pub password_hash: String,  // Never expose!
    pub created_at: DateTimeWithTimeZone,
}

// ✅ Same-file: use `name` parameter for OpenAPI schema name
vespera::schema_type!(Schema from Model, name = "UserSchema");

// ============================================
// src/routes/users.rs (Route handlers)
// ============================================
use vespera::schema_type;

// ✅ Cross-file: use descriptive struct names + pick/omit
// NO `name` parameter needed - struct name = OpenAPI schema name
schema_type!(CreateUserRequest from crate::models::user::Model, pick = ["name", "email"]);
schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]);
schema_type!(UserPatch from crate::models::user::Model, omit = ["password_hash", "id"], partial);

#[vespera::route(get, path = "/{id}")]
pub async fn get_user(Path(id): Path<i32>, State(db): State<DbPool>) -> Json<UserResponse> {
    let user = User::find_by_id(id).one(&db).await.unwrap().unwrap();
    Json(user.into())  // From impl handles conversion
}

#[vespera::route(patch, path = "/{id}")]
pub async fn patch_user(
    Path(id): Path<i32>,
    Json(patch): Json<UserPatch>,  // All fields are Option<T>
) -> Json<UserResponse> {
    // Apply partial update...
}
```

### Multipart Mode (`multipart`)

Generate `Multipart` structs from existing multipart request types:

```rust
use vespera::multipart::{FieldData, TypedMultipart};
use vespera::{Multipart, Schema};
use tempfile::NamedTempFile;

// Base multipart struct (manually defined)
#[derive(Multipart, Schema)]
pub struct CreateUploadRequest {
    pub name: String,
    #[form_data(limit = "10MiB")]
    pub thumbnail: Option<FieldData<NamedTempFile>>,
    #[form_data(limit = "50MiB")]
    pub document: Option<FieldData<NamedTempFile>>,
    pub tags: Option<String>,
}

// Derive a partial update struct via schema_type!
// - Derives Multipart (not serde)
// - All fields become Option<T> (partial)
// - "document" field excluded
// - #[form_data(limit = "10MiB")] preserved from source
schema_type!(PatchUploadRequest from CreateUploadRequest, multipart, partial, omit = ["document"]);
```

**What `multipart` mode changes:**

| Aspect | Normal Mode | Multipart Mode |
|--------|------------|----------------|
| Derives | `Serialize`, `Deserialize` | `Multipart` |
| Struct attrs | `#[serde(rename_all=...)]` | None |
| Field attrs | `#[serde(...)]` preserved | `#[form_data(...)]` preserved |
| Relation fields | Included (BelongsTo/HasOne) | **Skipped** (can't represent in forms) |
| `From` impl | Auto-generated | **Not generated** |

**OpenAPI rename alignment:** The schema parser reads `#[form_data(field_name = "...")]` and `#[serde(rename_all = "...")]` for multipart structs, ensuring OpenAPI field names match runtime multipart parsing.

**Dependencies required in your Cargo.toml:**
```toml
vespera = "0.1"                # Includes multipart support natively
tempfile = "3"                 # For NamedTempFile file uploads
```

### Quick Reference

```rust
// ✅ RECOMMENDED PATTERNS
schema_type!(CreateUserRequest from crate::models::user::Model, pick = ["name", "email"]);
schema_type!(CreatePostRequest from crate::models::post::Model, omit_default);
schema_type!(UserResponse from crate::models::user::Model, omit = ["password_hash"]);
schema_type!(UserListItem from crate::models::user::Model, pick = ["id", "name"]);

// ✅ MULTIPART PATTERNS
schema_type!(PatchUpload from CreateUploadRequest, multipart, partial);
schema_type!(SmallUpload from CreateUploadRequest, multipart, omit = ["document"]);

// ⚠️ USE SPARINGLY
schema_type!(UserPatch from crate::models::user::Model, partial);  // PATCH only
schema_type!(Schema from Model, name = "UserSchema");              // Same-file only

// ❌ AVOID
schema_type!(Schema from crate::models::user::Model, name = "UserResponse");  // Use struct name!
```

---

## Merging Multiple Vespera Apps

Combine routes and OpenAPI specs from multiple apps at compile time.

### export_app! Macro

Export an app for merging:

```rust
// Child crate (e.g., third/src/lib.rs)
mod routes;

// Basic - scans "routes" folder by default
vespera::export_app!(ThirdApp);

// Custom directory
vespera::export_app!(ThirdApp, dir = "api");
```

Generates:
- `ThirdApp::OPENAPI_SPEC: &'static str` - OpenAPI JSON
- `ThirdApp::router() -> Router` - Axum router

### merge Parameter

Merge child apps in parent:

```rust
let app = vespera!(
    openapi = "openapi.json",
    docs_url = "/docs",
    merge = [third::ThirdApp, other::OtherApp]
)
.with_state(state);
```

**What happens:**
1. Child routers merged into parent router
2. OpenAPI specs merged (paths, schemas, tags)
3. Swagger UI shows all routes

### How It Works (Compile-Time)

```
Child compilation (export_app!):
  1. Scan routes/ folder
  2. Generate OpenAPI spec
  3. Write to target/vespera/{Name}.openapi.json

Parent compilation (vespera! with merge):
  1. Generate parent OpenAPI spec
  2. Read child specs from target/vespera/
  3. Merge all specs together
  4. Write merged openapi.json
```

登录后下载/点赞/收藏 ❤ 25 | ★ 0

vespera

目录结构

SKILL.md

举报内容

提示