@@ -26,20 +26,22 @@ This approach provides:
2626- ** Client SDKs** : Automatically generated for multiple languages
2727- ** Reduced Boilerplate** : No manual HTTP handler writing
2828
29- ## Protobuf as the Contract
29+ ## Protocol as Contract
30+
31+ ### Single Source of Truth
32+
33+ Your ` .proto ` files serve as the authoritative definition of:
34+ - ** Data structures** (messages)
35+ - ** API operations** (services and methods)
36+ - ** Error conditions** (enums with metadata)
37+ - ** HTTP mapping** (via annotations)
38+ - ** Field constraints** (via validation rules)
3039
3140### Service Definitions
3241
3342Services define the operations your API supports:
3443
3544``` protobuf
36- syntax = "proto3";
37-
38- package api.v1;
39-
40- import "google/api/annotations.proto";
41- import "sphere/binding/binding.proto";
42-
4345service UserService {
4446 rpc GetUser(GetUserRequest) returns (User) {
4547 option (google.api.http) = {
@@ -53,19 +55,6 @@ service UserService {
5355 body: "*"
5456 };
5557 }
56-
57- rpc UpdateUser(UpdateUserRequest) returns (User) {
58- option (google.api.http) = {
59- put: "/v1/users/{id}"
60- body: "user"
61- };
62- }
63-
64- rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
65- option (google.api.http) = {
66- delete: "/v1/users/{id}"
67- };
68- }
6958}
7059```
7160
@@ -85,19 +74,155 @@ message User {
8574message GetUserRequest {
8675 int64 id = 1 [(sphere.binding.location) = BINDING_LOCATION_URI];
8776}
77+ ```
8878
89- message CreateUserRequest {
90- string name = 1 [(buf.validate.field).string.min_len = 1];
91- string email = 2 [(buf.validate.field).string.pattern = "^[^@]+@[^@]+$"];
92- }
79+ ### Error Definitions
9380
94- message UpdateUserRequest {
95- int64 id = 1 [(sphere.binding.location) = BINDING_LOCATION_URI];
96- User user = 2;
81+ Errors are defined as enums with rich metadata:
82+
83+ ``` protobuf
84+ import "sphere/errors/errors.proto";
85+
86+ enum UserError {
87+ option (sphere.errors.default_status) = 500;
88+
89+ USER_ERROR_UNSPECIFIED = 0;
90+ USER_ERROR_NOT_FOUND = 1001 [(sphere.errors.options) = {
91+ status: 404
92+ reason: "USER_NOT_FOUND"
93+ message: "User not found"
94+ }];
9795}
96+ ```
9897
99- message DeleteUserRequest {
100- int64 id = 1 [(sphere.binding.location) = BINDING_LOCATION_URI];
98+ ## Code Generation Pipeline
99+
100+ ### Generator Chain
101+
102+ The code generation happens in a specific order:
103+
104+ 1 . ** protoc-gen-go** : Generate base Go types
105+ 2 . ** protoc-gen-sphere-binding** : Add struct tags for binding
106+ 3 . ** protoc-gen-sphere** : Generate HTTP handlers and routing
107+ 4 . ** protoc-gen-sphere-errors** : Generate error types and handling
108+ 5 . ** protoc-gen-route** : Generate custom routing (optional)
109+
110+ ### What Gets Generated
111+
112+ From your proto definitions, you automatically get:
113+
114+ #### Server-side Code
115+ - ** Service interfaces** to implement
116+ - ** HTTP handlers** with proper routing
117+ - ** Request binding** with validation
118+ - ** Response marshaling** with proper headers
119+ - ** Error handling** with consistent formatting
120+
121+ #### Client-side Code
122+ - ** OpenAPI/Swagger documentation**
123+ - ** TypeScript SDKs** (optional)
124+ - ** Go client stubs** (if needed)
125+ - ** Validation schemas** for frontend use
126+
127+ #### Developer Tools
128+ - ** Interactive documentation** via Swagger UI
129+ - ** API testing** endpoints
130+ - ** Type definitions** for IDE support
131+
132+ ## Benefits of This Approach
133+
134+ ### Type Safety
135+ - Compile-time verification of API contracts
136+ - No runtime surprises from mismatched types
137+ - Automatic validation of required fields
138+ - IDE support with autocomplete and error checking
139+
140+ ### Consistency
141+ - Single source of truth for API definitions
142+ - Consistent naming across all generated code
143+ - Uniform error handling patterns
144+ - Standardized HTTP response formats
145+
146+ ### Developer Experience
147+ - Faster iteration cycles
148+ - Less boilerplate code to maintain
149+ - Clear separation of concerns
150+ - Automatic documentation updates
151+
152+ ### Scalability
153+ - Easy to add new services and methods
154+ - Version management built-in
155+ - Multiple output targets from one definition
156+ - Team coordination through shared contracts
157+
158+ ## Protocol Organization
159+
160+ ### Recommended Structure
161+ ```
162+ proto/
163+ ├── shared/v1/ # Common messages
164+ │ ├── user.proto
165+ │ └── common.proto
166+ ├── api/v1/ # Service definitions
167+ │ ├── user_service.proto
168+ │ └── auth_service.proto
169+ └── errors/v1/ # Error definitions
170+ ├── user_errors.proto
171+ └── common_errors.proto
172+ ```
173+
174+ ### Versioning Strategy
175+ - Use explicit version packages (` v1 ` , ` v2 ` )
176+ - Keep shared types separate from services
177+ - Plan for backwards compatibility
178+ - Document breaking changes clearly
179+
180+ ## Evolution and Maintenance
181+
182+ ### Adding New Features
183+ 1 . Define new messages/services in ` .proto `
184+ 2 . Run code generation
185+ 3 . Implement service methods
186+ 4 . Tests and documentation are automatically updated
187+
188+ ### API Versioning
189+ - Create new version packages for breaking changes
190+ - Maintain multiple versions simultaneously
191+ - Gradual migration paths for clients
192+ - Automatic deprecation warnings
193+
194+ ### Team Collaboration
195+ - Proto files as API contracts between teams
196+ - Code review focuses on API design
197+ - Generated code handles implementation details
198+ - Consistent patterns across all services
199+
200+ ## Best Practices
201+
202+ ### Proto Design
203+ 1 . ** Clear naming** : Use descriptive, consistent names
204+ 2 . ** Proper grouping** : Organize by domain and version
205+ 3 . ** Forward compatibility** : Design for future evolution
206+ 4 . ** Documentation** : Comment services, methods, and fields
207+
208+ ### Code Generation
209+ 1 . ** Frequent regeneration** : Update generated code early and often
210+ 2 . ** Don't edit generated files** : All changes go in ` .proto ` files
211+ 3 . ** Version control** : Commit both ` .proto ` and generated files
212+ 4 . ** Automation** : Integrate generation into build process
213+
214+ ### Error Handling
215+ 1 . ** Comprehensive coverage** : Define errors for all failure modes
216+ 2 . ** Appropriate status codes** : Use correct HTTP status codes
217+ 3 . ** Clear messages** : Write user-friendly error messages
218+ 4 . ** Structured data** : Include relevant context in errors
219+
220+ ## See Also
221+
222+ - [ API Definitions Guide] ( ../guides/api-definitions ) - Detailed HTTP mapping rules and examples
223+ - [ Error Handling Guide] ( ../guides/error-handling ) - Comprehensive error patterns and implementation
224+ - [ Code Generators] ( ../components/generators ) - Individual generator documentation and configuration
225+ - [ Project Structure] ( project-structure ) - How generated code fits into the overall project layout
101226}
102227```
103228
0 commit comments