go-template

command module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2024 License: Apache-2.0 Imports: 2 Imported by: 0

README

go-template

Template repo for golang graphql apis

Getting Started

This repo contains the basis for generating an opinionated Graph API using:

  1. ent - insane entity mapping tool, definitely not an ORM but kind of an ORM
  2. atlas - Schema generation and migration
  3. gqlgen - Code generation from schema definitions
  4. gqlgenc - client building utilities with GraphQL
  5. openfga - Authorization
  6. echo - High performance, extensible, minimalist Go web framework
  7. koanf - configuration management
  8. viper - command line flags / management
Dependencies

Setup Taskfile by following the instructions and using one of the various convenient package managers or installation scripts. You can then simply run task install to load the associated dependencies. Nearly everything in this repository assumes you already have a local golang environment setup so this is not included. Please see the associated documentation.

Usage

Cleanup
  1. After cloning the repo, you will need to update all occurrences of go-template with your repo name. For convenience, a task command is included:
task clean-template
Schema Generation with Ent
  1. As the tooling suggests, this is schema driven api development so first up, is defining your schema

  2. Create a new schema by running the following command, replacing <object> with your object:

    task newschema -- <object>
    

    For example, if you wanted to create a user, organization, and members schema you would run:

    task newschema -- User Organization Member
    
  3. This will generate a file per schema in internal/ent/schema

    tree internal/ent/schema
    
    internal/ent/schema
    └── user.go
    └── organization.go
    └── member.go
    
  4. You will add your fields, edges, annotations, etc to this file for each schema. See the ent schema def docs for more details.

  5. For a simple User, this might look something like :

    // Fields of the User.
    func (User) Fields() []ent.Field {
        return []ent.Field{
            field.Int("age").
                Positive(),
            field.String("name").
                Default("unknown"),
        }
    }
    
    // Edges of the User.
    func (User) Edges() []ent.Edge {
        return nil
    }
    
    func (User) Annotations() []schema.Annotation {
        return []schema.Annotation{
            entgql.QueryField(),
            entgql.Mutations(entgql.MutationCreate(), entgql.MutationUpdate()),
        }
    }
    
  6. Now that your schema is created, you want to generate your ent.graphql, this will contain all your graph Input types. The generate commands are setup in the Taskfile to make things easier:

    task generate
    
  7. This will create a schema/ent.graphql file

    tree schema
    
    schema
    ├── ent.graphql
    └── todo.graphql
    

    As well as generated ent files, including the openapi.json:

  8. This will have created a new internal/graphapi directory with a resolver per schema object

    internal/graphapi
    ├── doc.go
    ├── ent.resolvers.go
    ├── gen_models.go
    ├── gen_server.go
    ├── helpers.go
    ├── resolver.go
    └── todo.resolvers.go
    
  9. In the resolvers, there will be stubbed out CRUD operations based on the grapqhl schemas. The business logic and permissions checks should go in here:

    // CreateTodo is the resolver for the createTodo field.
    func (r *mutationResolver) CreateTodo(ctx context.Context, input CreateUserInput) (*User, error) {
        panic(fmt.Errorf("not implemented: CreateTodo - createTodo"))
    }
    
Dependencies

The Datum ecosystem has additional dependencies that were not included in the vanilla template because they will not be required for all services. These include things such as:

  1. Email Manager
  2. Task Manager
  3. Analytics Manager

To add these to your project, refer to the implementation in Datum

  1. Config Setup
  2. entc Setup
  3. Server Setup
Running locally
  1. Now that all the code is there, test it using the playground:
    task run-dev
    
  2. Using the default config, you should be able to go to your browser of choice and see the playground: http://localhost:1337/playground
  3. Via curl, http://localhost:1337/query
Creating DB Migrations
  1. Create DB Migrations with atlas:
    task atlas:create
    

Documentation

Overview

package main is the entry point

Directories

Path Synopsis
cmd
Package cmd is our cobra/viper cli implementation
Package cmd is our cobra/viper cli implementation
cli
cli/cmd
Package datum is our cobra/viper cli implementation
Package datum is our cobra/viper cli implementation
cli/cmd/version
Package version contains the version information for the CLI
Package version contains the version information for the CLI
Package config holds configuration stuff to configure the things
Package config holds configuration stuff to configure the things
Package db provides an embedded filesystem containing all the database migrations
Package db provides an embedded filesystem containing all the database migrations
internal
constants
Package constants contains constants used throughout the application
Package constants contains constants used throughout the application
ent/schema
Package schema contains the ent schema
Package schema contains the ent schema
entdb
Package entdb extends the ent db library and satisfies matt's needs for consistency
Package entdb extends the ent db library and satisfies matt's needs for consistency
graphapi
Package graphapi does graph stuff
Package graphapi does graph stuff
httpserve/config
Package config holds the echo server configuration utilities
Package config holds the echo server configuration utilities
httpserve/handlers
Package handlers contains custom handler functions
Package handlers contains custom handler functions
httpserve/route
Package route will hold the routes and route groups
Package route will hold the routes and route groups
httpserve/server
Package server contains the server functions
Package server contains the server functions
httpserve/serveropts
Package serveropts contains an echo server options wrapper
Package serveropts contains an echo server options wrapper
envparse
Package envparse provides a way to parse environment variables from a struct
Package envparse provides a way to parse environment variables from a struct
pkg
middleware/transaction
Package transaction implements a transaction middleware for REST endpoints using the ent db client
Package transaction implements a transaction middleware for REST endpoints using the ent db client

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL