https://github.com/spcent/golang_simple_server
Minimal Go HTTP server with routing, middleware, and graceful shutdown
https://github.com/spcent/golang_simple_server
framework golang http-server web-api websocket
Last synced: about 2 months ago
JSON representation
Minimal Go HTTP server with routing, middleware, and graceful shutdown
- Host: GitHub
- URL: https://github.com/spcent/golang_simple_server
- Owner: spcent
- Created: 2025-09-03T03:58:02.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-26T05:57:10.000Z (3 months ago)
- Last Synced: 2025-12-27T00:12:58.407Z (3 months ago)
- Topics: framework, golang, http-server, web-api, websocket
- Language: Go
- Homepage:
- Size: 474 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Minimal Go HTTP server with routing, middleware, and graceful shutdown
## Overview
A lightweight HTTP server skeleton built with the Go standard library.
It includes dynamic routing, middleware, graceful shutdown, and environment-based configuration — ideal for quickly building simple APIs or learning HTTP server development.
## Features
* **Dynamic Routing**: Supports path parameters like `/hello/:name`
* **Middleware System**: Built-in Logging and Auth middlewares, with support for custom extensions
* **Graceful Shutdown**: Cleans up connections within 5 seconds after receiving an interrupt signal
* **Logging**: Add glog logging library for structured logging
* **Env Configuration**: Supports `.env` files (e.g., log level, etc.)
* **Test Coverage**: Includes tests for routing, middleware, 404 handling, and more
* **Developer Toolchain**: Comes with a `Makefile` and `dev.sh` script for easy build/run/test workflows
* **Static Frontend Hosting**: Serve built Node/Next.js bundles directly from the Go server (flag: `-frontend-dir`, env: `FRONTEND_DIR`)
## Getting Started
### Requirements
* Go 1.18+
### Build & Run
```bash
# Using Makefile
make run # Build and start the server (default port: 8080)
# Or using the dev.sh script
./dev.sh run
```
### Custom Port
```bash
./golang_simple_server -addr :9090 # Start on port 9090
```
### Serve a built Node/Next.js frontend
Point the server at a production build directory (for example `next export` output in `./web/out`):
```bash
./golang_simple_server -frontend-dir ./web/out
# or
FRONTEND_DIR=./web/out ./golang_simple_server
```
The `-frontend-dir` flag has the highest priority and overrides `FRONTEND_DIR`.
All assets under the directory are served with SPA-style fallback to `index.html`, making it suitable for exported Next.js/Vite/React builds.
To ship a single self-contained binary, copy your built frontend (the same `frontend-dir` contents) into `pkg/frontend/embedded/` before building:
```bash
cp -r ./web/out/* pkg/frontend/embedded/
go build ./...
./golang_simple_server # mounts embedded assets when no frontend dir/env is provided
```
## Routing
Register parameterized routes with `app.(Get|Post|Delete|Put)` (see `main.go` for examples):
```go
app.Get("/hello/:name", func(w http.ResponseWriter, r *http.Request) {
params := router.ParamsFromContext(r.Context())
// Access params["name"]
fmt.Fprintf(w, `{"message":"Hello, %s!"}`, params["name"])
})
app.Get("/users/:id/posts/:postID", func(w http.ResponseWriter, r *http.Request) {
params := router.ParamsFromContext(r.Context())
// Access params["id"] and params["postID"]
fmt.Fprintf(w, `{"message":"User %s, Post %s"}`, params["id"], params["postID"])
})
```
## Route Testing
After starting the service, test the routes using curl:
```bash
curl http://localhost:8080/ping # pong
curl http://localhost:8080/hello # {"message":"Hello, World!"}
curl -H "X-Token: secret" http://localhost:8080/hello/Alice # {"message":"Hello, Alice!"}
```
## Middleware
* **LoggingMiddleware**: Logs request duration (`[time] METHOD PATH (duration)`)
* **AuthMiddleware**: Validates `X-Token` header
* **CorsMiddleware**: Allow cross-domain requests
Combine middlewares (see `main.go` for usage):
```go
app.Use(app.Logging(), app.Auth())
```
## Testing
```bash
make test # Run all tests
make coverage # Generate coverage report (outputs to coverage.html)
```
## Usage
* **[English](docs/en/usage.md)**: Comprehensive guide with examples
* **[中文](docs/cn/usage.md)**: 中文文档，包含详细的使用说明和示例
## License
MIT