1. Swagger/OpenAPI中的字符串基本校验
在swagger（openapi规范）中，对字符串类型进行校验是api设计中常见的需求，主要通过type、minlength和maxlength这几个关键字实现。
- type: string: 明确声明该字段为字符串类型。
- minLength: 定义字符串允许的最小长度。如果字符串的实际长度小于此值，则校验失败。
- maxLength: 定义字符串允许的最大长度。如果字符串的实际长度大于此值，则校验失败。
示例：基本长度限制
以下是一个Swagger YAML片段，展示了如何为一个字符串字段设置最小和最大长度。
components:
schemas:
AccountInfo:
type: object
properties:
accountId:
type: string
minLength: 70 # 最小长度为70
maxLength: 100 # 最大长度为100
example: "a7b3c9d1e5f7g9h1i3j5k7l9m1n3o5p7q9r1s3t5u7v9w1x3y5z7a9b1c3d5e7f9g1h3i5j7k9l1m3n5o7p9q1r3s5t7u9v1w3x5y7z9"
description: "账户唯一标识符，长度必须在70到100个字符之间。"在这个例子中，accountId字段的长度必须严格控制在70到100个字符之间。任何长度超出这个范围的字符串都将被视为无效。
2. 处理空字符串与Null值
在字符串校验中，经常需要区分空字符串（""）和null值。Swagger/OpenAPI通过不同的机制来处理这两种情况。
2.1 空字符串 ("") 的校验
空字符串的长度为0。在Swagger/OpenAPI中，minLength属性天然地解决了空字符串的校验问题。
- 禁止空字符串： 如果你希望字符串不能为空，只需将minLength设置为大于0的值（例如minLength: 1）。任何长度为0的空字符串都将不满足minLength: 1的条件，从而校验失败。
- 允许空字符串： 如果业务场景允许空字符串，可以将minLength设置为0。
在上面accountId的例子中，minLength: 70已经意味着空字符串（长度为0）是无效的，因为它不满足最小长度70的要求。
2.2 Null值的处理
null值表示字段不存在或未提供，这与空字符串（一个存在的、但内容为空的字符串）不同。Swagger/OpenAPI通过required关键字来控制是否允许字段为null。
- 禁止null值： 如果字段被标记为required: true，则该字段必须存在且不能为null。
- 允许null值： 如果字段未被标记为required（默认行为），或者明确设置为required: false，则允许该字段为null。
示例：允许Null但禁止空字符串
假设一个字段允许为null，但如果提供了值，则该值不能是空字符串，且有特定的长度范围。
components:
schemas:
ProductDetails:
type: object
properties:
productName:
type: string
minLength: 1 # 禁止空字符串
maxLength: 255
example: "Premium Widget"
description: "产品名称，允许为null，但如果提供则不能为空字符串，长度在1到255之间。"
required: # 明确指定哪些属性是必需的
- productId # 假设productId是必需的，productName不是在上述ProductDetails的例子中：
- productName字段没有在required列表中，这意味着它可以是null。
- 但是，如果productName被提供了一个非null值，那么这个值的minLength: 1将确保它不能是一个空字符串。
3. 校验逻辑的内部机制
从编程实现的角度来看，Swagger/OpenAPI的校验逻辑可以概括为以下步骤：
-
检查null值：
- 如果输入值为null：
- 如果字段被定义为required: true，则校验失败。
- 如果字段未被定义为required或required: false，则校验通过。
- 如果输入值为null：
-
检查字符串长度（仅当非null时）：
- 如果输入值为非null字符串：
- 获取字符串的实际长度。
- 如果存在minLength且实际长度小于minLength，则校验失败。
- 如果存在maxLength且实际长度大于maxLength，则校验失败。
- 如果输入值为非null字符串：
- 其他校验： 如果通过了上述所有检查，并且没有其他如pattern、format等校验规则失败，则校验通过。
这种分层的校验逻辑确保了即使在允许null的情况下，非null的字符串值也能满足其自身的长度和内容约束。
4. 注意事项与最佳实践
- minLength: 0的含义： 如果你明确希望允许空字符串，请将minLength设置为0。例如，一个可选的备注字段可能允许为空字符串。
- required与minLength的协同： 理解required关键字控制null值，而minLength控制非null字符串的最小长度。它们是相互独立的但又协同工作的校验规则。
- 清晰的描述和示例： 在Swagger定义中，为每个字段提供清晰的description和example，这对于API消费者理解校验规则至关重要。
- x-constraint-messages等扩展： 某些工具或框架支持自定义错误消息（如原问题中的x-constraint-messages），这有助于提供更友好的用户反馈。但这属于特定实现，并非OpenAPI规范核心部分。
通过精确地使用type、minLength、maxLength和required这些关键字，开发者可以在Swagger/OpenAPI中构建出强大且清晰的字符串校验规则，从而确保API接收的数据符合预期，提高系统的健壮性。
