Skip to content

Commit 81f0482

Browse files
lvan100lianghuan
lvan100
authored and
lianghuan
committed
feat(gen): add README.md
1 parent cc80bed commit 81f0482

File tree

14 files changed

+808
-34
lines changed

14 files changed

+808
-34
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Run golangci-lint
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
lint:
11+
name: Run golangci-lint
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v4
16+
17+
- name: Print All environment variables
18+
run: env | sort
19+
20+
- name: Set up Go
21+
uses: actions/setup-go@v5
22+
23+
- name: Install golangci-lint
24+
uses: golangci/golangci-lint-action@v7
25+
with:
26+
version: latest
27+
28+
- name: Run golangci-lint
29+
run: golangci-lint run ./...

‎.github/workflows/test.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Run tests and upload coverage
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
name: Run tests and collect coverage
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Print All environment variables
18+
run: env | sort
19+
20+
- name: Set up Go
21+
uses: actions/setup-go@v5
22+
23+
- name: Install dependencies
24+
run: go mod download
25+
26+
- name: Run tests
27+
run: go test -count=1 -coverprofile=coverage.txt ./...
28+
29+
- name: Upload results to Codecov
30+
uses: codecov/codecov-action@v5
31+
with:
32+
token: ${{ secrets.CODECOV_TOKEN }}
33+
slug: go-spring/gs-http-gen

‎README.md‎

Lines changed: 180 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,180 @@
1-
# gen
1+
# gs-http-gen
2+
3+
<div>
4+
<img src="https://img.shields.io/github/license/go-spring/gs-http-gen" alt="license"/>
5+
<img src="https://img.shields.io/github/go-mod/go-version/go-spring/gs-http-gen" alt="go-version"/>
6+
<img src="https://img.shields.io/github/v/release/go-spring/gs-http-gen?include_prereleases" alt="release"/>
7+
<a href="https://codecov.io/gh/go-spring/gs-http-gen" >
8+
<img src="https://codecov.io/gh/go-spring/gs-http-gen/graph/badge.svg?token=SX7CV1T0O8" alt="test-coverage"/>
9+
</a>
10+
<a href="https://deepwiki.com/go-spring/gs-http-gen"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
11+
</div>
12+
13+
[English](README.md) | [中文](README_CN.md)
14+
15+
## Project Overview
16+
17+
**gs-http-gen** is an HTTP code generation tool based on **IDL (Interface Definition Language)**, designed for the *
18+
*Go-Spring** framework. It can automatically generate HTTP server and client code from interface definitions, including
19+
data models, validation logic, and route bindings.
20+
21+
The tool aims to simplify the development workflow of Go web services. By using declarative IDL definitions, it
22+
generates boilerplate code automatically, improving development efficiency and reducing human errors.
23+
24+
More importantly, IDL is not only used for code generation—it also serves as a unified contract and documentation for
25+
APIs across frontend-backend teams and departments. With standardized IDL definitions, key details such as request
26+
parameters, response formats, and validation rules become clear, reducing communication costs and ensuring API
27+
consistency and correctness.
28+
29+
## Features
30+
31+
- **IDL-driven**: Define service interfaces and data models using a simple interface definition language.
32+
- **Automatic code generation**: Generate Go code from IDL files, including:
33+
- Data model structs
34+
- Data validation logic
35+
- HTTP route bindings
36+
- Server interface definitions
37+
- Client call code
38+
- **Rich type support**: Supports basic types, structs, enums, lists, optional types, etc.
39+
- **Data validation**: Built-in validation rules with support for custom validators.
40+
- **HTTP parameter binding**: Automatically bind HTTP request parameters (path, query, header, body) to data models.
41+
- **Type embedding**: Supports type inheritance and field reuse to reduce redundancy.
42+
- **Flexible configuration**: Generate server code, client code, or both.
43+
- **Enum support**: Enum types with optional string serialization.
44+
- **Streaming support**: Generate streaming RPC interfaces.
45+
- **Annotation support**: Add Markdown-style comments in IDL (not yet implemented).
46+
47+
## Installation
48+
49+
**Recommended**: Install via the **gs** integrated development tool,
50+
see [https://github.com/go-spring/gs](https://github.com/go-spring/gs).
51+
52+
To install this tool separately:
53+
54+
```bash
55+
go install github.com/go-spring/gs-http-gen@latest
56+
```
57+
58+
## Usage
59+
60+
### Step 1: Define an IDL file
61+
62+
First, create an IDL file to define service interfaces and data models:
63+
64+
```idl
65+
// Define constants
66+
const int MAX_AGE = 150
67+
const int MIN_AGE = 18
68+
69+
// Define enums
70+
enum ErrCode {
71+
ERR_OK = 0
72+
PARAM_ERROR = 1003
73+
}
74+
75+
enum Department {
76+
ENGINEERING = 1
77+
MARKETING = 2
78+
SALES = 3
79+
}
80+
81+
// Define data structures
82+
type Manager {
83+
string id
84+
string name (validate="len($) > 0 && len($) <= 64")
85+
int? age (validate="$ >= MIN_AGE && $ <= MAX_AGE")
86+
Department dept
87+
}
88+
89+
type Response<T> {
90+
ErrCode errno = ErrCode.ERR_OK (validate="OneOfErrCode($)")
91+
string errmsg
92+
T data
93+
}
94+
95+
// Define request and response
96+
type ManagerReq {
97+
string id (path="id")
98+
}
99+
100+
type GetManagerResp Response<Manager?>
101+
102+
// Define streaming types
103+
type StreamReq {
104+
string id
105+
}
106+
107+
type StreamResp {
108+
string id
109+
string data
110+
}
111+
112+
// Define RPC interface
113+
rpc GetManager(ManagerReq) GetManagerResp {
114+
method="GET"
115+
path="/managers/{id}"
116+
summary="Get manager info by ID"
117+
}
118+
119+
// Example of streaming interface
120+
rpc Stream(StreamReq) stream<StreamResp> {
121+
method="GET"
122+
path="/stream/{id}"
123+
summary="Stream data transfer"
124+
}
125+
```
126+
127+
### Step 2: Generate code
128+
129+
Use the CLI tool to generate code:
130+
131+
```bash
132+
# Generate server code only (default)
133+
gs-http-gen --server --output ./generated --package myservice
134+
135+
# Generate both server and client code
136+
gs-http-gen --server --client --output ./generated --package myservice
137+
```
138+
139+
Command-line options:
140+
141+
* `--server`: Generate server code (HTTP handlers, route bindings, etc.)
142+
* `--client`: Generate client code (HTTP call wrappers)
143+
* `--output`: Output directory for generated code (default: current directory)
144+
* `--package`: Go package name (default: "proto")
145+
* `--language`: Target language (currently only `"go"` supported)
146+
147+
### Step 3: Use the generated code
148+
149+
The generated code includes data models, validation logic, and HTTP handlers:
150+
151+
```go
152+
// Implement service interface
153+
type MyManagerServer struct{}
154+
155+
func (m *MyManagerServer) GetManager(ctx context.Context, req *proto.ManagerReq) *proto.GetManagerResp {
156+
// Business logic
157+
data := proto.NewManager()
158+
data.SetName("Jim")
159+
res := proto.NewGetManagerResp()
160+
res.SetData(data)
161+
return res
162+
}
163+
164+
func (m *MyManagerServer) Stream(ctx context.Context, req *proto.StreamReq, resp chan<- *proto.StreamResp) {
165+
// Streaming logic
166+
for i := 0; i < 5; i++ {
167+
resp <- &proto.StreamResp{
168+
Id: strconv.Itoa(i),
169+
}
170+
}
171+
}
172+
173+
// Register routes
174+
mux := http.NewServeMux()
175+
proto.InitRouter(mux, &MyManagerServer{})
176+
```
177+
178+
## License
179+
180+
This project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)