api-go-template's Introduction

api-go-template

A boilerplate Go repo that comes with:

Dependency Injection using uber-go/fx (:tv: video)
DB Migration Tool using golang-migrate (:tv: video)
ORM using sqlboiler (:tv: video)
Env Var Configs using go-envconfig
gRPC using connect-go
Protobufs, compiled, formatted, linted, and more with Buf
Command-Line Interface using cobra

These libraries do a lot of heavy lifting in terms of boilerplate.

For example:

The fx framework manages dependency injection and application life-cycle for you. (See example_test.go).
sqlboiler makes DB CRUD really simple. (See foo.go). Raw queries are supported as an escape hatch.

Project structure

Directory	Description
`./cmd`	CLI for making gRPC requests
`./idl`	Protobufs (Interface Definition Language)
`./internal/app`	App dependency injection / initialization
`./internal/idl`	Auto-generated protobufs
`./internal/models`	Auto-generated ORM / models
`./internal/service`	Service layer / Business logic
`./internal/service/db`	Data layer
`./schema`	SQL migration scripts

Getting started

# Step 1: Start containers in detached (background) mode
docker-compose up -d

# Step 2: Create the database schema
make migrate-up

# Step 3: Start app
go run main.go

Finally, hit the API (using HTTPie)

# Create a new Foo
http POST \
  http://localhost:8081/coop.drivers.foo.v1beta1.FooService/CreateFoo \
    name="Kevin"

# Get existing Foo
http POST \
  http://localhost:8081/coop.drivers.foo.v1beta1.FooService/GetFoo \
    id="cb4c4rnrirfucgsert7g"

Or with curl:

curl -X POST http://localhost:8081/coop.drivers.foo.v1beta1.FooService/CreateFoo \
  -H "Content-Type: application/json" \
  -d '{"name": "Kevin"}'

curl -X POST http://localhost:8081/coop.drivers.foo.v1beta1.FooService/GetFoo \
  -H "Content-Type: application/json" \
  -d '{"id": "cb4c4rnrirfucgsert7g"}'

Database

Run Migrations

make migrate-up

or you can run:

docker run -v $(pwd)/schema:/migrations \
  --network host \
  --rm \
  migrate/migrate \
  -path=/migrations/ \
  -database postgres://postgres:postgres@localhost:5432/foo\?sslmode=disable \
  up

This will run all migrations in ./schema.

Create New Migration

To create a new migration called create-new-table, run:

docker run -v $(pwd)/schema:/migrations \
  --network host \
  --rm \
  migrate/migrate \
  -path=/migrations/ \
  create \
  -dir /migrations \
  -ext sql \
  create-new-table

This will create a new up and down migration in ./schema.

Auto-generate ORM DB Models

We have a sqlboiler command that introspects the DB and generates ORM models.

make gen-models

Configuration comes from sqlboiler.toml

Telemetry

Traces

See traces in Jaeger here

Metrics

See metrics in Prometheus here.

api-go-template's People

Contributors

Stargazers

Watchers

api-go-template's Issues

GH Actions

Unit tests
Integration tests
Lint Go
Buf Lint + Breaking Change Detection

Remote Generation

From remote generation docs:

A common frustration when working with Protocol Buffers is that you need to generate code for each language that you're working with. Many teams implement custom tooling and scripts to solve this problem, but it can be difficult to ensure that every person who works on a given project has all of the code generation tooling set up locally. And if you have Protobuf-based APIs, the consumers of your APIs shouldn't have to deal with code generation.

The Buf Schema Registry solves this problem with remote code generation. With this feature, you can eliminate code generation from your workflows and directly install code generated from Protobuf definitions using standard package managers and build tools. This diagram illustrates how remote generation works: