Things I've learned using gRPC for ~10 years:

1. I really like gRPC and protos for the codegen capabilities. APIs I've worked on that use gRPC have always been really easy to extend. I am always tempted to hand-roll http.Handle("/foo", func(w http.ResponseWriter, req *http.Request) { ... }), but gRPC is even easier than this.

2. grpc-web never worked well for me. It's hard to debug; in the browser's inspector you just have serialized protos instead of JSON, and developers find this hard to debug. Few people know about `protoc --decode[-raw]` options. (This comes up a lot when working with protos; you have binary or base64-encoded protos but just want key/value pairs. I ended up adding a command to our CLI to do this for you.)

I also thought the client side of the equation was a little too bloated. webpack and friends never tree-shook out code we didn't call, and as a result, the client bundle was pretty giant for how simple of an app we had. There are also too many protoc plugins for the frontend, and I feel like whenever a team goes looking for one, they pick the wrong one. I am sure I have picked the wrong one multiple times. After many attempts at my last job, I found the sane Typescript one. But at my current job, a team started using gRPC and picked the other one, which caused them a lot of pain.

3. grpc-gateway works pretty well, though. Like grpc-web, it suffers from promised HTTP features never being implemented, so it can't implement all of gRPC. (gRPC is really just bidirectional RPCs, but you can restrict what you do to have unary RPCs, server streaming RPCs, client streaming RPCs, and bidirectional RPCs. The web really only handles unary and server streaming. grpc-gateway doesn't remove these grpc-web limitations.)

But overall, I like it a lot for REST APIs. If I were building a new REST API from scratch today, it would be gRPC + grpc-gateway. I like protos for specifying how the API works, and grpc-gateway turns it into a Swagger file that normal developers can understand. No complaints whatsoever with any of it. (buf is unnecessary, and I feel like they just PR'd themselves into the documentation to sound like it's required, but honestly if it helps people, good for them. I just have a hand-crafted protoc invocation that works perfectly.)

4. For plain server-to-server communication, you'd expect gRPC to work fine, but you learn that there are middleboxes that still don't support HTTP/2. One problem that we have is that our CLI uses gRPC to talk to our server. Customers self-host all of this, and often work at companies that break gRPC because their middleboxes don't support HTTP/2. (I'll point out here that HTTP/3 is the current version of HTTP.) We have Zscaler at work and this mostly affects our internal customers. (We got acquired and had these conditions added 8 years into the development cycle, so we didn't anticipate them, obviously.) But if we were starting all over today, I'd use grpc-gateway-over-http1.1 instead of grpc-over-http2. The API would adjust accordingly; I wouldn't have bidirectional RPCs, but RPCs that simulate them. Something like a create session RPC, then a unary call to add another message to the session, and a unary call that returns when a message is ready. It sucks, but that's all that HTTP/1.1 in the browser really offers, and that's the maximum web compatibility level that works in Corporate America these days.

5. Some details are really confusing and opaque to end users trying to debug things. Someone set up a proxy. They connected to dns:///example.com and the proxy doesn't work properly. This is because gRPC resolves example.com and dials the returned IP addresses, and sets :authority to the IP addresses and not the hostname. You have to use passthrough:///example.com to have the HTTP machinery make an HTTP request for example.com/foopb/Foo.Method. Maybe this is Go specific, but it always confuses people. A little too many features available out of the box, that again work great on networks you control, but poorly on networks that your employer controls.