Protobuf Practices and Lessons Learned at Laiye Technology

Laiye Technology migrated from JSON to Protobuf for inter‑service communication to improve serialization performance, reduce payload size, and enforce stronger schema contracts across hundreds of microservices.

Protobuf, a language‑neutral, efficient data description format designed by Google, produces much smaller serialized messages and faster (de)serialization compared with JSON, as demonstrated by several benchmark tests on integer fields, strings, and mixed structures.

During large‑scale adoption the team encountered several problems: inconsistent naming of messages and fields, enum conflicts, backward‑compatibility breaks when fields are removed or changed, high compilation costs across multiple languages, divergent import paths, and duplicated client‑side code for timeouts, retries, and keep‑alive settings.

To address these issues they defined strict naming conventions (CamelCase for messages, snake_case for fields, uppercase enum values with a prefix, Request/Response suffixes, sequential field numbers, and deprecation annotations) and enforced them through a refined review process that requires all Protobuf changes to originate from the main branch and pass static scans before merging.

They built a unified CI pipeline that packages all language‑specific Protobuf compilers into a Docker image, automatically triggers Jenkins jobs via a webhook on main‑branch commits, and publishes the generated code to language‑specific repositories.

For client generation they extended the gapic‑generator‑go to embed common options (retry policies, keep‑alive, multi‑link load‑balancing, and client version injection) directly into the generated gRPC client, eliminating the need for manual boilerplate.

Version management is handled by tagging the compiled Protobuf artifacts with Git tags that align with product releases (e.g., v1.0.x), allowing developers to import specific versions via Go modules, Maven, or pip.

Swagger documentation for the external RESTful APIs is automatically produced from the Protobuf definitions using protoc‑gen‑swagger and rendered with Redoc, with documentation versions also tied to Git tags.

Overall, by defining Protobuf once they achieve multi‑purpose benefits—efficient serialization, automatic API documentation, consistent client libraries, and streamlined CI/CD—greatly reducing development overhead and improving reliability across the organization.

//图片格式
enum ImageFileType {
    IMAGE_DEFAULT=0;
    IMAGE_PNG=1;
    IMAGE_JPEG=2;
}