OpenLark Validation Style
🧭 技能路由指南
本技能适用场景：
-
需要统一/评审 validate() 方法写法
-
不确定使用 validate_required! （宏）还是 validate_required() （函数）
-
需要处理空白字符串校验
-
需要聚合多条校验错误
其他技能：
-
项目级代码规范检查（架构/API/导出/校验一体）→ Skill(openlark-code-standards)
-
添加/重构 API → Skill(openlark-api)
-
审查整体设计规范 → Skill(openlark-design-review)
关键词触发映射
-
validate、必填校验、validate_required、空白字符串、校验聚合 → openlark-validation-style
-
代码规范、规范检查、风格一致性、体检 → openlark-code-standards
-
架构设计、public API、收敛方案、feature gating、兼容策略 → openlark-design-review
-
新增 API、重构 API、Builder、Request/Response、mod.rs 导出 → openlark-api
-
覆盖率、缺失 API、实现数量、CSV 对比 → openlark-api-validation
双向跳转规则
-
若校验问题已扩展到命名/导出/端点体系，转 openlark-code-standards 。
-
若校验争议本质是架构范式冲突（例如 Request/Service 边界），转 openlark-design-review 。
目标
在各 feature crate 的请求/Builder validate(&self) -> SDKResult<()> 中统一：
-
必填字段校验写法（减少样板代码）
-
空白字符串是否视为缺失（避免不同 crate 行为漂移）
-
失败时返回的错误类型与消息风格
规则
- 默认：在 validate() 内使用 openlark_core::validate_required! （宏）快速失败
适用场景：必填校验失败就应该立即返回 Err(...) 。
注意：该宏内部用 .is_empty() 判空，不会自动 trim() 。
字符串字段一律传入 .trim() 结果，保证空白字符串也视为缺失：
fn validate(&self) -> openlark_core::SDKResult<()> { openlark_core::validate_required!(self.app_token.trim(), "app_token 不能为空"); openlark_core::validate_required!(self.table_id.trim(), "table_id 不能为空"); Ok(()) }
非字符串容器（如 Vec<T> ）可直接传字段（按“长度是否为 0”判空）：
fn validate(&self) -> openlark_core::SDKResult<()> { openlark_core::validate_required!(self.items, "items 不能为空"); Ok(()) }
- 需要自定义控制流（不立刻 return / 聚合多条错误）时，使用 openlark_core::validation::validate_required （函数）
适用场景：
-
需要做多条校验后统一返回（例如收集多个错误）
-
需要明确的 trim() 语义（函数内部 trim() 后判空）
注意：函数只返回 bool ，你需要自己决定错误消息与返回时机：
fn validate(&self) -> openlark_core::SDKResult<()> { if !openlark_core::validation::validate_required(&self.name, "name") { return Err(openlark_core::CoreError::validation_msg("name 不能为空")); } Ok(()) }
- 禁止在 feature crate 内重复定义 validate_required! （或同语义宏）
统一复用 openlark_core::validate_required! ，避免各 crate 的判空规则/错误类型不一致。
速查
-
“校验失败立即返回” → openlark_core::validate_required!(field[.trim()], "...")
-
“空白也算空” → 字符串传 .trim() ，或使用函数 openlark_core::validation::validate_required
-
“多条校验汇总再返回” → 函数 validate_required
- 自定义聚合逻辑