Skip to content

index.md

Latest commit

 

History

History
151 lines (109 loc) · 4.72 KB

index.md

File metadata and controls

151 lines (109 loc) · 4.72 KB

Usage Guidance

For commands, please refer to the guidance of each below. Behavior of commands depends on their execution scopes, namely: Global, Project, Service.

Gokums project

Projects generated by Gok are called Gokums projects. They are defined by the root.yaml configuration file. A service is a subfolder inside the project and defined by the manifest.yaml file.

The scope of the command is defined by the current folder you are in. If your current folder is in the service scope, this means you are in a folder that contains a manifest.yaml or one of your parent folders has it. project scope means that you are not in a service, but your current folder or its parent contains a root.yaml. Global scope implies that your current folder is not in any project or service.

The diagram below demonstrates this:

development
└── a_gok_ms
    ├── services
    │   ├── service_x
    │   │   ├── client
    │   │   │   ├── client_test.go
    │   │   │   └── client.go
    │   │   ├── manifest.yml
    │   │   ├── main.go
    │   │   └── main_test.go
    │   └── service_y
    │       └── ...
    └── vendor

$ cd development
# Currently global scope
$ cd a_gok_ms
# Currently project scope
$ cd services
# Currently project scope
$ cd service_x
# Currently service scope (of service_x)
$ cd client
# Currently service scope (of service_x)

Gokums command list

To allow typing of commands faster, refer to the Command alias guide. Check Gokums conventions for better understanding of the Gokums implementation.

Create a new project

The generate command will be used to create the basic project, derived from the standard template structure.

Note, the generate command can be abbreviated to g. This also assumes GitHub is the repository for code, and therefore the path follows golang conventions.

echo go navigate setup > ~/.bash_rc
source ~/.bash_rc
gok g project github.com/gokums/sample
gokto gokums-sample
git remote add origin git@github.com:orgname/projectname.git
git push -u origin master

Generate Interface specifications

See Generate Gateway below for specific Proto generation details for API Gateway services.

Define specification

Protobuf proto files are used to define the interfaces for deployable components.

Assumption: These commands are executed from the root project directory. In the example created above, that will be $GOPATH/src/github.com/orgname/projectname.

gok g proto protoname

This will create a subdirectory containing the proto file which can be updated with your specifications. Note, there is additional commenting in the proto file which explains how to configure optional proto validations.

Generate golang files

The build command (aliased to b) is used to compile proto files into the necessary golang source.

# Build a single proto file
gok b proto protofile
# Build all proto files
gok b proto
# Build a single proto file with validations enabled
gok b proto protofile -v

Generate Gateway

proto files will also be used to define a Gateway's API specification.

Define gateway specification

gok g gateway gatewayprotofile

This will define proto file in the proto\gateway subdirectory.

This proto can be built in the same way as other proto files, using the gok b proto command.

Create service

This applies to the creation of both Gateway services, or other standard services.

gok g service servicename

This creates service golang code, and associated configurations files in the src\servicename subdirectory.

If you wish to logically arrange other services into packages, you can create a service using the following command.

gok g service servicename1 -p helpers
gok g service servicename2 -p helpers

This will create src\service\helpers\servicename1 and src\service\helpers\servicename2.

Other utility tooling

Project Source navigation

This is done by using the navigate command, which is aliased to nav. projectname is a project that was previously created using the generate command.

Refer to Gok navigate for further details.