在Utoipa中为数值参数设置最小最大值限制

在使用Rust开发Web API时，我们经常需要对传入的数值参数进行范围校验。Utoipa作为一个强大的OpenAPI规范生成工具，提供了多种方式来定义这些校验规则。

基本用法

对于实现了ToSchema特性的结构体，我们可以直接在字段上使用#[schema]属性来设置数值范围：

#[derive(serde::Deserialize, Debug, ToSchema)]
struct Position {
    #[schema(maximum = 360.0, minimum = 0.0)]
    ra: f64,
    #[schema(maximum = 90.0, minimum = -90.0)]
    dec: f64,
    name: String,
    #[schema(minimum = 0.0)]
    radius: Option<f64>,
}

这样生成的OpenAPI规范会自动包含这些校验规则，前端开发者或API使用者就能清楚地知道每个参数的合法取值范围。

工作原理

Utoipa会将这些schema属性转换为OpenAPI规范中的相应约束：

1. maximum和minimum分别对应OpenAPI中的最大最小值约束
2. 对于可选字段(Option)，约束同样适用
3. 这些约束会体现在生成的API文档中

高级用法

除了基本的最大最小值，Utoipa还支持其他数值约束：

#[derive(ToSchema)]
struct Measurement {
    #[schema(maximum = 100.0, exclusive_maximum = true)] // 必须小于100
    temperature: f64,
    #[schema(minimum = 0.0, multiple_of = 0.5)] // 必须是0.5的倍数
    adjustment: f64,
}

最佳实践

1. 明确文档：为所有数值字段设置合理的范围约束，这能减少无效请求
2. 考虑业务逻辑：设置的范围应该反映实际业务需求，而不仅仅是技术限制
3. 保持一致性：相同含义的字段在整个API中应该使用相同的约束
4. 测试验证：确保生成的OpenAPI规范确实包含了这些约束

通过合理使用Utoipa的schema属性，我们可以在API设计阶段就定义好清晰的参数约束，这不仅能改善API的可用性，还能减少后续开发中的边界条件错误。