protovalidate
v0.9.0
protovalidate 는 사용자 정의 유효성 검사 규칙을 기반으로 런타임에 Protobuf 메시지의 유효성을 검사하도록 설계된 일련의 라이브러리입니다. Google의 CEL(Common Expression Language)을 기반으로 맞춤 유효성 검사 규칙을 정의하고 평가하기 위한 유연하고 효율적인 기반을 제공합니다. protovalidate 의 주요 목표는 개발자가 생성된 코드를 요구하지 않고도 네트워크 전체에서 데이터 일관성과 무결성을 보장할 수 있도록 돕는 것입니다.
메모
protovalidate protoc-gen-validate의 정신적 후속 버전입니다. 코드 생성이 필요하지 않으며 사용자 지정 제약 조건을 지원합니다.
신규 및 기존 프로젝트를 protoc-gen-validate 대신 protovalidate 사용으로 전환하는 것이 좋습니다.
protoc-gen-validate 의 제한 사항과 protovalidate 더 좋게 설계한 방법에 대해 자세히 알아보려면 블로그 게시물을 읽어보세요.
이 저장소는 protovalidate 프로젝트의 핵심입니다. 여기에는 다음이 포함됩니다.
protovalidate 효과적으로 적용하는 방법protoc-gen-validate 에서 점진적으로 마이그레이션protovalidate 사용하는 .proto 파일 예시protovalidate 구현의 승인 테스트용 protovalidate 의 런타임 구현은 자체 저장소에서 찾을 수 있습니다.
protovalidate-go (베타 릴리스)protovalidate-cc (베타 릴리스)protovalidate-java (베타 릴리스)protovalidate-python (베타 릴리스)protovalidate-ts (곧 제공 예정)다른 언어에 대한 지원을 추가하고 싶으십니까? 기여 가이드라인을 확인하세요.
Protobuf 메시지 내에서 제약 조건을 정의하려면 buf/validate/validate.proto .proto 파일로 가져옵니다.
syntax = "proto3" ;
package my.package ;
import "buf/validate/validate.proto" ;buf 로 빌드하기 모듈의 buf.yaml 에 buf.build/bufbuild/protovalidate 에 대한 종속성을 추가합니다.
version : v1
# <snip>
deps :
- buf.build/bufbuild/protovalidate
# <snip> buf.yaml 수정한 후에는 buf mod update 실행하여 종속성을 최신 상태로 유지하는 것을 잊지 마세요.
protoc 으로 빌드 protoc 호출에 proto/protovalidate 디렉터리의 콘텐츠를 가리키는 가져오기 경로( -I 플래그)를 추가합니다.
protoc
-I ./vendor/protovalidate/proto/protovalidate
# <snip> buf.validate Protobuf 패키지를 사용하여 유효성 검사 제약 조건을 적용할 수 있습니다. 규칙은 .proto 파일에 직접 지정됩니다.
몇 가지 예를 고려해 보겠습니다.
스칼라 필드 유효성 검사: 기본 User 메시지의 경우 사용자 이름의 최소 길이와 같은 제약 조건을 적용할 수 있습니다.
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message User {
// User's name, must be at least 1 character long.
string name = 1 [ (buf.validate .field ) .string .min_len = 1 ];
} 맵 필드 유효성 검사: 항목 수량 맵이 포함된 Product 메시지의 경우 모든 수량이 양수인지 확인할 수 있습니다.
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message Product {
// Map of item quantities, all quantities must be positive.
map < string , int32 > item_quantities = 1 [ (buf.validate .field ) .map.values.int32 .gt = 0 ];
} WKT(잘 알려진 유형) 유효성 검사: User 메시지의 경우 created_at 타임스탬프가 과거인지 확인하기 위한 제약 조건을 추가할 수 있습니다.
syntax = "proto3" ;
import "google/protobuf/timestamp.proto" ;
import "buf/validate/validate.proto" ;
message User {
// User's creation date must be in the past.
google.protobuf.Timestamp created_at = 1 [ (buf.validate .field ) .timestamp .lt_now = true ];
} 고급 또는 사용자 지정 제약 조건의 경우 protovalidate 필드 전체에 걸쳐 정보를 통합할 수 있는 CEL 표현식을 허용합니다.
필드 수준 표현식: 문자열로 전송된 제품 price 에 "$" 또는 "£"와 같은 통화 기호가 포함되도록 강제할 수 있습니다. 우리는 가격이 양수이고 통화 기호가 유효한지 확인하고 싶습니다.
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message Product {
string price = 1 [ (buf.validate .field ).cel = {
id : "product.price" ,
message : "Price must be positive and include a valid currency symbol ($ or £)" ,
expression : "(this.startsWith('$') || this.startsWith('£')) && double(this.substring(1)) > 0"
}];
} 메시지 수준 표현식: Transaction 메시지의 경우 메시지 수준 CEL 표현식을 사용하여 delivery_date 항상 purchase_date 이후인지 확인할 수 있습니다.
syntax = "proto3" ;
import "google/protobuf/timestamp.proto" ;
import "buf/validate/validate.proto" ;
message Transaction {
google.protobuf.Timestamp purchase_date = 1 ;
google.protobuf.Timestamp delivery_date = 2 ;
option (buf.validate .message ).cel = {
id : "transaction.delivery_date" ,
message : "Delivery date must be after purchase date" ,
expression : "this.delivery_date > this.purchase_date"
};
} 표현식에서 오류 메시지 생성: CEL 표현식에서 직접 사용자 정의 오류 메시지를 생성할 수 있습니다. 이 예에서 age 18세 미만인 경우 CEL 표현식은 오류 메시지 문자열로 평가됩니다.
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message User {
int32 age = 1 [ (buf.validate .field ).cel = {
id : "user.age" ,
expression : "this < 18 ? 'User must be at least 18 years old': ''"
}];
} 표준 제약조건과 사용자 정의 CEL 제약조건 모두에 대한 examples 확인하세요.
메시지에 제약조건 주석이 추가되면 지원되는 언어 라이브러리 중 하나를 사용하여 유효성을 검사합니다. 추가 코드 생성이 필요하지 않습니다.
protovalidate 다양한 데이터 유형에 대한 표준 및 사용자 지정 제약 조건을 적용하고 유효성 검사 위반이 발생할 때 자세한 오류 정보를 제공하여 Protobuf 메시지 유효성을 검사하기 위한 강력한 프레임워크를 제공합니다. 모든 구성 요소, 지원되는 제약 조건 및 이를 효과적으로 사용하는 방법에 대한 자세한 개요는 포괄적인 설명서를 참조하세요. 주요 구성 요소는 다음과 같습니다.
표준 제약 조건 : protovalidate 모든 필드 유형에 대한 광범위한 표준 제약 조건과 Protobuf Well-Known-Types에 대한 특수 기능을 지원합니다. Protobuf 메시지에 이러한 제약 조건을 적용하여 특정 공통 조건을 충족하는지 확인할 수 있습니다.
맞춤 제약 조건 : Google의 CEL(Common Expression Language)을 사용하면 protovalidate 사용하면 필드 및 메시지 수준 모두에서 표준 제약 조건이 적용되지 않는 고유한 검증 시나리오를 처리하기 위한 복잡한 맞춤 제약 조건을 만들 수 있습니다.
오류 처리 : 위반이 발생하면 protovalidate 자세한 오류 정보를 제공하여 신속하게 원인을 식별하고 문제를 해결하는 데 도움을 줍니다.
protovalidate 는 protoc-gen-validate 의 정신적 후속 버전으로, 사용자 정의 코드 생성 없이 원래 플러그인에 있는 동일한 기능을 모두 제공하고 CEL의 복잡한 제약 조건을 설명하는 새로운 기능을 제공합니다.
protovalidate 의 제약 조건은 protoc-gen-validate 의 제약 조건과 매우 유사하므로 개발자가 쉽게 전환할 수 있습니다. protoc-gen-validate 에서 protovalidate 로 마이그레이션하려면 제공된 마이그레이션 도구를 사용하여 .proto 파일을 점진적으로 업그레이드하세요.
Apache 2 라이센스에 따라 제공됩니다.
