[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-a8d729aa-7e28-4f74-ba16-d804560525e8":3,"$fsvjoWWS1ViCgOyIH30rme3zjxe5PAN-6TKWKndZ3Ufo":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"a8d729aa-7e28-4f74-ba16-d804560525e8","grpc-golang","使用Go和mTLS、流式传输和可观测性构建生产就绪的gRPC服务。在设计Protobuf契约时使用Buf或实现安全的服务间传输时使用。","cat_life_career","mod_other","sickn33,other","---\nname: grpc-golang\ndescription: \"Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport.\"\nrisk: safe\nsource: self\ndate_added: \"2026-02-27\"\n---\n\n# gRPC Golang (gRPC-Go)\n\n## Overview\n\nComprehensive guide for designing and implementing production-grade gRPC services in Go. Covers contract standardization with Buf, transport layer security via mTLS, and deep observability with OpenTelemetry interceptors.\n\n## Use this skill when\n\n- Designing microservices communication with gRPC in Go.\n- Building high-performance internal APIs using Protobuf.\n- Implementing streaming workloads (unidirectional or bidirectional).\n- Standardizing API contracts using Protobuf and Buf.\n- Configuring mTLS for service-to-service authentication.\n\n## Do not use this skill when\n\n- Building pure REST\u002FHTTP public APIs without gRPC requirements.\n- Modifying legacy `.proto` files without the ability to introduce a new API version (e.g., `api.v2`) or ensure backward compatibility.\n- Managing service mesh traffic routing (e.g., Istio\u002FLinkerd), which is outside the application code scope.\n\n## Step-by-Step Guide\n\n1. **Confirm Technical Context**: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc.\n2. **Confirm Requirements**: Identify mTLS needs, load patterns (unary\u002Fstreaming), SLOs, and message size limits.\n3. **Plan Schema**: Define package versioning (e.g., `api.v1`), resource types, and error mapping.\n4. **Security Design**: Implement mTLS for service-to-service authentication.\n5. **Observability**: Configure interceptors for tracing, metrics, and structured logging.\n6. **Verification**: Always run `buf lint` and breaking change checks before finalizing code generation.\n\nRefer to `resources\u002Fimplementation-playbook.md` for detailed patterns, code examples, and anti-patterns.\n\n## Examples\n\n### Example 1: Defining a Service & Message (v1 API)\n\n```proto\nsyntax = \"proto3\";\npackage api.v1;\noption go_package = \"github.com\u002Forg\u002Frepo\u002Fgen\u002Fapi\u002Fv1;apiv1\";\n\nservice UserService {\n  rpc GetUser(GetUserRequest) returns (GetUserResponse);\n}\n\nmessage User {\n  string id = 1;\n  string name = 2;\n}\n\nmessage GetUserRequest {\n  string id = 1;\n}\n\nmessage GetUserResponse {\n  User user = 1;\n}\n```\n\n## Best Practices\n\n- ✅ **Do:** Use Buf to standardize your toolchain and linting with `buf.yaml` and `buf.gen.yaml`.\n- ✅ **Do:** Always use semantic versioning in package paths (e.g., `package api.v1`).\n- ✅ **Do:** Enforce mTLS for all internal service-to-service communication.\n- ✅ **Do:** Handle `ctx.Done()` in all streaming handlers to prevent resource leaks.\n- ✅ **Do:** Map domain errors to standard gRPC status codes (e.g., `codes.NotFound`).\n- ❌ **Don't:** Return raw internal error strings or stack traces to gRPC clients.\n- ❌ **Don't:** Create a new `grpc.ClientConn` per request; always reuse connections.\n\n## Troubleshooting\n\n- **Error: Inconsistent Gen**: If the generated code does not match the schema, run `buf generate` and verify the `go_package` option.\n- **Error: Context Deadline**: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers.\n- **Error: mTLS Handshake**: Ensure the CA certificate is correctly added to the `x509.CertPool` on both client and server sides.\n\n## Limitations\n\n- Does not cover service mesh traffic routing (Istio\u002FLinkerd configuration).\n- Does not cover gRPC-Web or browser-based gRPC integration.\n- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g., `grpc.Dial` vs `grpc.NewClient`).\n- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX).\n- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint.\n\n## Resources\n\n- `resources\u002Fimplementation-playbook.md` for detailed patterns, code examples, and anti-patterns.\n- [Google API Design Guide](https:\u002F\u002Fcloud.google.com\u002Fapis\u002Fdesign)\n- [Buf Docs](https:\u002F\u002Fbuf.build\u002Fdocs)\n- [gRPC-Go Docs](https:\u002F\u002Fgrpc.io\u002Fdocs\u002Flanguages\u002Fgo\u002F)\n- [OpenTelemetry Go Instrumentation](https:\u002F\u002Fopentelemetry.io\u002Fdocs\u002Finstrumentation\u002Fgo\u002F)\n\n## Related Skills\n\n- @golang-pro - General Go patterns and performance optimization outside the gRPC layer.\n- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers.\n- @api-design-principles - Resource naming and versioning strategy before writing `.proto` files.\n- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,122,409,"2026-05-16 13:21:29",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"其他","other","mdi-page-next-outline","其他类型Skill",5,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"职场发展","career","mdi-briefcase-outline","面试准备、简历优化、职业规划",4,575,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"62747fbc-4d7b-495a-b7c9-c74e38add377","1.0.0","grpc-golang.zip",7523,"uploads\u002Fskills\u002Fa8d729aa-7e28-4f74-ba16-d804560525e8\u002Fgrpc-golang.zip","d26eb082619d583dd800d9cbcbe0b2508d7be34204822d2f29c025f318efb5b9","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":4590},{\"path\":\"resources\u002Fimplementation-playbook.md\",\"isDirectory\":false,\"size\":15018}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]