170 lines
3.7 KiB
Markdown
170 lines
3.7 KiB
Markdown
# Go Microservices
|
|
|
|
Go-based microservices backend with a REST API gateway, gRPC service-to-service communication, JWT auth, and local observability tooling.
|
|
|
|
## Overview
|
|
|
|
This repo contains:
|
|
|
|
- `api-gateway`: public HTTP API (`/api/v1/*`)
|
|
- `services/auth-service`: authentication and user auth workflows
|
|
- `services/user-service`: user domain service
|
|
- `services/post-service`: post domain service
|
|
- `proto`: shared protobuf contracts used by gateway and services
|
|
|
|
Core infra for local development includes PostgreSQL, Redis, Docker Compose, Prometheus, Grafana, and Jaeger.
|
|
|
|
## Project Layout
|
|
|
|
```text
|
|
go-microservices/
|
|
├── api-gateway/
|
|
├── services/
|
|
│ ├── auth-service/
|
|
│ ├── user-service/
|
|
│ └── post-service/
|
|
├── proto/
|
|
├── scripts/
|
|
├── docker-compose.yml
|
|
├── Makefile
|
|
└── README.md
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
Prerequisites:
|
|
|
|
- Go 1.21+
|
|
- Docker + Docker Compose
|
|
- `protoc`
|
|
- `make`
|
|
|
|
Local startup:
|
|
|
|
```bash
|
|
make dev-setup
|
|
make db-up
|
|
make proto
|
|
|
|
# run each in separate terminals
|
|
make run-auth
|
|
make run-user
|
|
make run-post
|
|
make run-gateway
|
|
```
|
|
|
|
Docker-first startup:
|
|
|
|
```bash
|
|
make docker-build
|
|
make docker-up
|
|
make docker-logs
|
|
```
|
|
|
|
## API Summary
|
|
|
|
Base URL: `http://localhost:8080/api/v1`
|
|
|
|
Endpoints:
|
|
|
|
- `GET /` health check
|
|
- `POST /signup` register
|
|
- `POST /signin` login (returns `access_token`, `refresh_token`)
|
|
- `POST /validate` validate token
|
|
- `POST /userinfo` protected endpoint (`Authorization: Bearer <token>`)
|
|
- `POST /test` create test entry
|
|
- `GET /tests` list test entries
|
|
|
|
Typical auth flow:
|
|
|
|
1. `POST /signup`
|
|
2. `POST /signin`
|
|
3. Use `access_token` as `Bearer` token on protected routes
|
|
4. (Optional) `POST /validate`
|
|
|
|
## Service Ports
|
|
|
|
- API Gateway: `8080`
|
|
- Auth gRPC: `50051`
|
|
- User gRPC: `50052`
|
|
- Post gRPC: `50053`
|
|
- PostgreSQL: `5432`
|
|
- Redis: `6379`
|
|
- Grafana: `3000`
|
|
- Prometheus: `9090`
|
|
- Jaeger: `16686`
|
|
|
|
## Testing Options
|
|
|
|
### 1) Postman
|
|
|
|
- Import `postman_collection.json`
|
|
- Import `postman_environment.json`
|
|
- Set `base_url=http://localhost:8080`
|
|
- Run requests in this order: health -> signup -> signin -> validate -> userinfo -> test -> tests
|
|
|
|
### 2) Posting (terminal TUI)
|
|
|
|
```bash
|
|
./scripts/posting-start.sh
|
|
```
|
|
|
|
Environment file used by Posting:
|
|
|
|
- `~/.config/posting/collections/go_microservices/Go Microservices API.env`
|
|
|
|
### 3) curl
|
|
|
|
```bash
|
|
# Health
|
|
curl -X GET http://localhost:8080/api/v1/
|
|
|
|
# Sign in
|
|
curl -X POST http://localhost:8080/api/v1/signin \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"email":"john@example.com","password":"SecurePassword123!"}'
|
|
```
|
|
|
|
## Common Make Targets
|
|
|
|
- `make build` build all services
|
|
- `make test` run tests
|
|
- `make lint` run linting
|
|
- `make format` format code
|
|
- `make proto` regenerate protobuf output
|
|
- `make db-up` / `make db-down` start/stop DB infra
|
|
- `make docker-up` / `make docker-down` start/stop container stack
|
|
|
|
## Protobuf Regeneration
|
|
|
|
When proto contracts change, regenerate bindings:
|
|
|
|
```bash
|
|
make proto
|
|
```
|
|
|
|
Direct command example:
|
|
|
|
```bash
|
|
protoc --go_out=. --go-grpc_out=. proto/auth.proto
|
|
```
|
|
|
|
Generated files are expected in service proto directories such as:
|
|
|
|
- `services/auth-service/proto/`
|
|
- `services/user-service/proto/`
|
|
- `services/post-service/proto/`
|
|
|
|
## Troubleshooting
|
|
|
|
- Port conflicts: stop local stack (`make docker-down`) and restart required services
|
|
- DB errors: run `make db-down && make db-up`
|
|
- Token errors (`401`): sign in again and ensure `Bearer` prefix is present
|
|
- 404/connection errors: verify `base_url` and gateway process on `:8080`
|
|
|
|
## Notes
|
|
|
|
- API returns JSON for most responses; errors typically use `{ "error": "..." }`
|
|
- JWT can be passed via `Authorization` header (or cookie where supported)
|
|
- Keep docs and contract examples in sync when changing endpoint behavior
|