Español

English

Español

English

Appearance

Ficheros .proto ​

En Sword, los ficheros .proto definen el contrato público de tu servicio gRPC. Este contrato luego se convierte en código Rust mediante tonic y tonic-prost-build (ver Compilando protos).

Ubicación recomendada ​

Recomendamos guardar los .proto bajo config/proto/.

Esto facilita:

  • mantener una estructura predecible entre proyectos,
  • reutilizar el mismo patrón en build.rs,
  • separar contratos de transporte del resto del código de aplicación.

Ejemplo:

text
config/
  proto/
    users.proto

Convenciones de naming ​

Estas reglas buscan evitar ambigüedad con servicios internos de tu aplicación y mantener contratos claros para clientes externos.

Services ​

Usa el sufijo GrpcService en servicios proto, porque en tu código de aplicación pueden coexistir servicios de negocio con nombres similares.

proto
service UserGrpcService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}
proto
service UserService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}

Métodos RPC ​

Nombra métodos por intención (Get, List, Create, Update, Delete, Stream) para que el contrato sea autoexplicativo para quien lo consume.

proto
rpc GetUser (GetUserRequest) returns (GetUserResponse);
rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
rpc StreamUsers (StreamUsersRequest) returns (stream User);
proto
rpc UserGet (GetUserRequest) returns (GetUserResponse);
rpc DoUserAction (ListUsersRequest) returns (ListUsersResponse);

Messages ​

Evita prefijos/sufijos técnicos como Grpc en message. En contratos públicos, es mejor usar nombres neutrales y orientados al dominio.

proto
message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}
proto
message GetUserGrpcRequest {
  string id = 1;
}

message GetUserGrpcResponse {
  UserGrpcModel user = 1;
}