{"id":31826035,"url":"https://github.com/go-spring/gs-http-gen","last_synced_at":"2025-10-11T16:57:16.804Z","repository":{"id":306740820,"uuid":"1026496894","full_name":"go-spring/gs-http-gen","owner":"go-spring","description":"An HTTP code generation tool based on IDL, Support modern syntax such as emptiness, generics, and type embeddings.","archived":false,"fork":false,"pushed_at":"2025-10-02T01:54:28.000Z","size":187,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-02T03:33:27.480Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-spring.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-26T02:32:16.000Z","updated_at":"2025-10-02T01:54:31.000Z","dependencies_parsed_at":"2025-07-27T11:21:46.833Z","dependency_job_id":"17767007-7930-424f-ae0e-24af9b21af80","html_url":"https://github.com/go-spring/gs-http-gen","commit_stats":null,"previous_names":["go-spring/gs-gen","go-spring/gs-http-gen"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/go-spring/gs-http-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spring%2Fgs-http-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spring%2Fgs-http-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spring%2Fgs-http-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spring%2Fgs-http-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-spring","download_url":"https://codeload.github.com/go-spring/gs-http-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-spring%2Fgs-http-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007970,"owners_count":26084369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T16:57:12.518Z","updated_at":"2025-10-11T16:57:16.798Z","avatar_url":"https://github.com/go-spring.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gs-http-gen\n\n\u003cdiv\u003e\n   \u003cimg src=\"https://img.shields.io/github/license/go-spring/gs-http-gen\" alt=\"license\"/\u003e\n   \u003cimg src=\"https://img.shields.io/github/go-mod/go-version/go-spring/gs-http-gen\" alt=\"go-version\"/\u003e\n   \u003cimg src=\"https://img.shields.io/github/v/release/go-spring/gs-http-gen?include_prereleases\" alt=\"release\"/\u003e\n   \u003ca href=\"https://codecov.io/gh/go-spring/gs-http-gen\" \u003e \n      \u003cimg src=\"https://codecov.io/gh/go-spring/gs-http-gen/graph/badge.svg?token=SX7CV1T0O8\" alt=\"test-coverage\"/\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://deepwiki.com/go-spring/gs-http-gen\"\u003e\u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n[English](README.md) | [中文](README_CN.md)\n\n\u003e This project is under continuous development, and its features and capabilities are being actively enhanced.\n\n`gs-http-gen` is an **IDL (Interface Definition Language)-based HTTP code generation tool**.\nIt can generate **Go server-side code** and **client-side code in other languages** based on unified interface\ndefinitions. The server-side code includes:\n\n* Data models\n* Validation logic\n* HTTP route binding\n* Support for both regular and streaming (SSE) interfaces\n\nBy using a declarative IDL description, developers can focus on business logic while reducing boilerplate code\nand human errors.\n\nAdditionally, IDL serves as a **contract and documentation for cross-team and frontend-backend collaboration**,\nhelping teams reduce communication overhead and ensure interface consistency.\n\n## Features\n\n### 🌟 IDL-Driven\n\n* Define services and data models using a concise interface definition language.\n* Supports:\n\n    * Constants, enums, structs, and `oneof` types\n    * Generics and type embedding (field reuse)\n    * RPC interface definitions\n    * Custom annotations (e.g., `json`, `go.type`, `enum_as_string`, etc.)\n\n### ⚙️ Automatic Code Generation\n\nGenerate Go server-side code and client code in other languages from IDL files:\n\n* Data model structures\n* Parameter and data validation logic\n* Automatic HTTP request parameter binding (path, query, header, body)\n* Support for both regular and streaming (SSE) interfaces\n* Server interface definitions and route binding\n* Client-side call code\n\n### 📦 Rich Data Type Support\n\n* Basic types: `bool`, `int`, `float`, `string`\n* Advanced types: `list`, `map`, `oneof`\n* Nullable fields: supported via `?` suffix\n* Type redefinitions and generics\n\n### 🔎 Efficient Data Validation\n\n* High performance, reflection-free implementation\n* Expression-based validation rules\n* Auto-generated `OneOfXXX` validation functions for enums\n* Custom validation functions supported\n\n### 🌐 HTTP-Friendly\n\n* Automatic binding of HTTP request parameters (path, query, header, body)\n* Supports `form`, `json`, and `multipart-form` formats\n* Native support for streaming RPC (SSE) interfaces\n\n### 📝 Comments \u0026 Documentation\n\n* Supports single-line and multi-line comments\n* Planned support for Markdown comments for richer documentation generation\n\n## Installation\n\n* **Recommended:**\n\nUse the [gs](https://github.com/go-spring/gs) integrated development tool.\n\n* **Standalone installation:**\n\n```bash\ngo install github.com/go-spring/gs-http-gen@latest\n```\n\n## Usage\n\n### Step 1: Define IDL Files\n\nCreate `.idl` files to describe your services and data models.\n\n\u003e **Syntax Notes:**\n\u003e\n\u003e * A document consists of zero or more definitions, separated by newlines or semicolons, and ends with EOF.\n\u003e * Identifiers consist of letters, digits, and underscores, but cannot start with a digit.\n\u003e * Use `?` to denote nullable fields.\n\n**Example:**\n\n```idl\n// Constants\nconst int MAX_AGE = 150 // years\nconst int MIN_AGE = 18  // years\n\n// Enums\nenum ErrCode {\n    ERR_OK = 0\n    PARAM_ERROR = 1003\n}\n\nenum Department {\n    ENGINEERING = 1\n    MARKETING = 2\n    SALES = 3\n}\n\n// Data structures\ntype Manager {\n    string id\n    string name (validate=\"len($) \u003e 0 \u0026\u0026 len($) \u003c= 64\")\n    int? age (validate=\"$ \u003e= MIN_AGE \u0026\u0026 $ \u003c= MAX_AGE\")\n    Department dept (enum_as_string)\n}\n\ntype Response\u003cT\u003e {\n    ErrCode errno (validate=\"OneOfErrCode($)\")\n    string errmsg\n    T data\n}\n\n// Request \u0026 response types\ntype ManagerReq {\n    string id (path=\"id\")\n}\n\ntype GetManagerResp Response\u003cManager?\u003e\n\n// Regular RPC interface\nrpc GetManager(ManagerReq) GetManagerResp {\n    method=\"GET\"\n    path=\"/managers/{id}\"\n    summary=\"Get manager info by ID\"\n}\n\n// Streaming RPC example\ntype StreamReq {\n    string ID (json=\"id\")\n}\n\ntype StreamResp {\n    string id\n    string data\n    Payload payload\n}\n\noneof Payload {\n    string text_data\n    int? numberData (json=\"number_data\")\n    bool boolean_data (json=\"\")\n}\n\n// Streaming RPC\nrpc Stream(StreamReq) stream\u003cStreamResp\u003e {\n    method=\"GET\"\n    path=\"/stream/{id}\"\n    summary=\"Stream data by ID\"\n}\n```\n\n### Step 2: Generate Code\n\nRun the CLI tool to generate code:\n\n```bash\n# Generate server-side code only (default)\ngs-http-gen --server --output ./generated --go_package myservice\n\n# Generate both server-side and client-side code\ngs-http-gen --server --client --output ./generated --go_package myservice\n```\n\n**Command-line options:**\n\n| Option         | Description                                         | Default |\n|----------------|-----------------------------------------------------|---------|\n| `--server`     | Generate server-side code (HTTP handlers \u0026 routing) | false   |\n| `--client`     | Generate client-side code (HTTP call wrappers)      | false   |\n| `--output`     | Output directory                                    | `.`     |\n| `--go_package` | Go package name for generated code                  | `proto` |\n| `--language`   | Target language (currently only `go`)               | `go`    |\n\n### Step 3: Use the Generated Code\n\n**Example:**\n\n```go\n// Implement the service interface\ntype MyManagerServer struct{}\n\nfunc (m *MyManagerServer) GetManager(ctx context.Context, req *proto.ManagerReq) *proto.GetManagerResp {\n    // Regular response\n    return \u0026proto.GetManagerResp{\n        Data: \u0026proto.Manager{\n            Id:   \"1\",\n            Name: \"Jim\",\n            Dept: proto.Department_ENGINEERING,\n        },\n    }\n}\n\nfunc (m *MyManagerServer) Stream(ctx context.Context, req *proto.StreamReq, resp chan\u003c- *proto.StreamResp) {\n    // Streaming response\n    for i := 0; i \u003c 5; i++ {\n        resp \u003c- \u0026proto.StreamResp{\n            Id: strconv.Itoa(i),\n            Payload: proto.Payload{\n                TextData: \"data\",\n            },\n        }\n    }\n}\n\n// Register routes\nmux := http.NewServeMux()\nproto.InitRouter(mux, \u0026MyManagerServer{})\n\nhttp.ListenAndServe(\":8080\", mux)\n```\n\n## ⚠️ Notes\n\n* Generated code does **not** enforce required fields; you must handle this in your business logic.\n* Validation logic does not automatically invoke `Validate()`; invoke it explicitly as needed for deep validation.\n* It’s recommended to manage generated code centrally and keep it in sync with IDL files to avoid divergence.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-spring%2Fgs-http-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-spring%2Fgs-http-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-spring%2Fgs-http-gen/lists"}