Подводные камни gRPC

• Контракты — используй.proto‑файлы, а не protobuf‑net; один класс = один файл + package
  
• Nullable для примитивов — optional int не даёт int?, нужны google/protobuf/wrappers.proto
  
• Nullable для ссылочных типов и enum — кодогенератор не различает optional и без него; enum получает HasXxx/ClearXxx вместо Nullable<T>
  
• Decimal — типа нет, используй DecimalValue по рецепту Microsoft или money.proto; избегай implicit operator
  
• DateTime — используй google/protobuf/timestamp.proto; DateTime требует предварительного.ToUniversalTime()
  
• Наследование — заменяется композицией; два подхода: от дочерних к родительским (читаемее) или от родительских к дочерним (удобнее при работе с базовым классом)
  
• Дженерики — три стратегии: специализированные сообщения (безопаснее), oneof (компромисс), google.protobuf.Any (гибко, но без type safety)
  
• Enum — имена значений должны быть уникальны в рамках всего файла; первое значение обязано быть 0; используй префикс <ИмяEnum>_<ИмяЗначения>
  
• Object — четыре всадника апокалипсиса: Any, oneof, google.protobuf.Value/Struct, ручная сериализация в bytes/string

• Один класс = один proto-файл (рекомендуется) + обязательно используем package (аналог namespace в мире protobuf) для разграничения имён
  
• Однако, если количество классов по объему не столько большое как у нас, то можете разбить их по использованию в один файл

<ItemGroup>
  <!-- Модели: не привязаны ни к Server, ни к Client -->
  <Protobuf Include="Protos\Models\**\*.proto">
    <GrpcServices>None</GrpcServices>
    <Access>Public</Access>
    <ProtoCompile>True</ProtoCompile>
    <ProtoRoot>Protos</ProtoRoot> <!-- Корень откуда будут смотреть ваши import -->
  </Protobuf>
  <!-- Сервисы -->
  <Protobuf Include="Protos\Services\**\*.proto">
    <GrpcServices>Server</GrpcServices> <!-- Both - если вам нужен и клиент и сервер -->
    <Access>Public</Access>
    <ProtoCompile>True</ProtoCompile>
    <ProtoRoot>Protos</ProtoRoot>
    <CompileOutputs>True</CompileOutputs>
  </Protobuf>
</ItemGroup>

• google/protobuf/money.proto - содержит сумму и валюту (строĸа).
  
• DecimalValue по рецепту Microsoft

public static class DecimalValueExtension
{
    private const decimal NanoFactor = 1_000_000_000;
    public static decimal ToDecimal(this DecimalValue value)
      => value.Units + value.Nanos / NanoFactor;
    public static decimal? ToNullableDecimal(this DecimalValue? value)
      => value is null ? null : value.ToDecimal();
    public static DecimalValue ToDecimalValue(this decimal value)
    {
        var units = decimal.ToInt64(value);
        var nanos = decimal.ToInt32((value - units) * NanoFactor);
        return new DecimalValue { Units = units, Nanos = nanos };
    }
    public static DecimalValue? ToNullableDecimalValue(this decimal? value)
      => value is null ? null : value.Value.ToDecimalValue();
}

• Для Timestamp: ToDateTime() и ToDateTimeOffset()
  
• В Timestamp:
  • Из DateTime: Для того, чтобы преобразовать DateTime в Timestamp необходимо сначала привести его к UTC, воспользовавшись методом ToUniversalTime(), а затем вызвать метод ToTimestamp()
    
  • Из DateTimeOffset: работает с .ToTimestamp() напрямую, без предварительных преобразований.

[abstract] class Base
{
    public int Id { get; set; }
}
class User : Base
{
    public string Name { get; set; }
}
class UserAdditionalInfo : User
{
    public DateTimeOffset BDay { get; set; }
}
class Role : Base
{
    public int Priority { get; set; }
    public string RoleName { get; set; }
}
class UseBaseClass
{
    public Base Base { get; set; }
}

syntax = "proto3";
message Base {
    int32 id = 1;
}
message User {
    Base base = 1;
    string name = 2;
}
message UserAdditionalInfo {
    User base = 1;
    google.protobuf.Timestamp b_day = 2;
}
message Role {
    Base base = 1;
    int32 priority = 2;
    string role_name = 3;
}
// Нужен только если есть метод/класс, работающий с базовым типом
message BaseChildrens {
    oneof type {
        User user = 1;
        UserAdditionalInfo user_additional_info = 2;
        Role role = 3;
    }
}
message UseBaseClass {
    BaseChildrens base = 1;
}

syntax = "proto3";
// Если будет метод, который принимает базовый/абстрактный класс, то можно передать его
message Base {
    int32 id = 1;
    oneof child {
        User user = 2;
        Role role = 3;
    }
}
message User {
  string name = 1;
    oneof child {
        UserAdditionalInfo user_additional_info = 2;
    }
}
message UserAdditionalInfo {
    google.protobuf.Timestamp b_day = 1;
}
message Role {
    int32 priority = 1;
    string role_name = 2;
}
message UseBaseClass {
    Base base = 1; // все так же используется одна из реализаций
}

class BaseEntity<T>
{
    public T Id { get; set; }
}
class User : BaseEntity<int>
{
    // ...
}
class Role : BaseEntity<long>
{
    // ...
}
class BaseEntityWrapper
{
    public BaseEntity<string> BaseEntity { get; set; }
}

syntax = "proto3";
message BaseEntity_Int {
    int32 id = 1;
}
message BaseEntity_Long {
    int64 id = 1;
}
message BaseEntity_String {
    string id = 1;
}
message User {
    BaseEntity_Int base = 1; // подход "от дочерних к родительским"
}
message Role {
    BaseEntity_Long base = 1;
}
message BaseEntityWrapper {
    BaseEntity_String base_entity = 1; // здесь не наследование
}

message BaseEntity {
    oneof id {
        int32  id_int32  = 1;
        int64  id_int64  = 2;
        string id_string = 3;
    }
}
message BaseEntityWrapper {
    BaseEntity base_entity = 1;
}

var proto = new BaseEntity();
if (entity is BaseEntity<int> intEntity)
    proto.IdInt32 = intEntity.Id;
else if (entity is BaseEntity<long> longEntity)
    proto.IdInt64 = longEntity.Id;
else if (entity is BaseEntity<string> strEntity)
    proto.IdString = strEntity.Id;

import "google/protobuf/any.proto";
message BaseEntityWrapper {
    google.protobuf.Any base_entity = 1;
}

// Pack
var userEntity = new UserEntity { Id = 42 };
var wrapper = new BaseEntityWrapper
{
    BaseEntity = Any.Pack(userEntity)
};
// Unpack
if (wrapper.BaseEntity.Is(UserEntity.Descriptor))
{
    var user = wrapper.BaseEntity.Unpack<UserEntity>();
}

syntax = "proto3";
enum PositionTypes {
    Up = 1;
    Down = 2; // злодей № 1 !!!
    Both = 3;
}
enum GraphMovementTypes {
    Upper = 0;
    Down = 1; // злодей № 2 !!! - не обязательно должны совпадать значения
    None = 2;
}

syntax = "proto3";
enum PositionTypes {
    PositionTypes_Up = 0;
    PositionTypes_Down = 10;
    PositionTypes_Both = 20;
}
enum GraphMovementTypes {
    GraphMovementTypes_Upper = 0;
    GraphMovementTypes_Down = 1;
}

import "google/protobuf/any.proto";
message Container {
    google.protobuf.Any value = 1;
}

// Pack
var container = new Container();
container.Value = Any.Pack(new UserEntity { Id = 1 });
// Unpack - нужно знать тип заранее
if (container.Value.Is(UserEntity.Descriptor))
{
    var user = container.Value.Unpack<UserEntity>();
}
// Unpack - через type_url если тип неизвестен
var typeUrl = container.Value.TypeUrl; // "type.googleapis.com/UserEntity"

message DynamicValue {
    oneof value {
        int32   int_val    = 1;
        int64   long_val   = 2;
        double  double_val = 3;
        string  str_val    = 4;
        bool    bool_val   = 5;
        bytes   bytes_val  = 6;
    }
}
message Container {
    DynamicValue value = 1;
}

// Запись
var val = new DynamicValue();
val.StrVal = "hello";          // object str = "hello"
val.IntVal = 42;               // object num = 42
// Чтение
var result = val.ValueCase switch
{
    DynamicValue.ValueOneofCase.StrVal    => (object)val.StrVal,
    DynamicValue.ValueOneofCase.IntVal    => (object)val.IntVal,
    DynamicValue.ValueOneofCase.DoubleVal => (object)val.DoubleVal,
    _ => null
};

import "google/protobuf/struct.proto";
message Container {
    google.protobuf.Value value  = 1;  // любой скалярный тип
    google.protobuf.Struct config = 2; // аналог Dictionary<string, object>
    google.protobuf.ListValue tags = 3; // аналог List<object>
}

// Value — скаляры
var container = new Container();
container.Value = Value.ForString("hello");
container.Value = Value.ForNumber(3.14);
container.Value = Value.ForBool(true);
container.Value = Value.ForNull();
// Struct — как Dictionary<string, object>
container.Config = new Struct();
container.Config.Fields["name"]  = Value.ForString("Alice");
container.Config.Fields["age"]   = Value.ForNumber(30);
container.Config.Fields["roles"] = Value.ForList(
    Value.ForString("admin"),
    Value.ForString("user")
);
// Чтение
var kind = container.Value.KindCase;  // StringValue, NumberValue, etc.
var name = container.Config.Fields["name"].StringValue;

• Как работать с библиотекой Grpc.Tools: Protocol Buffers/gRPC Codegen Integration Into .NET Build
  
• Рекомендации по структуре файлов proto: 1-1-1 Best Practice
  
• Лучшие практики proto: Proto Best Practices
  
• Работа с генератором кода protoc: C# Generated Code Guide
  
• Типы данных C# и Proto: Create Protobuf messages for .NET apps