Tutorials on Go

The Go programming language is designed to address the types of software infrastructure issues Google faced back in late 2007. At this time, Google predominantly built their infrastructure using the programming languages C++, Java and Python. With a large codebase and having to adapt to rapid technological changes in both computing and key infrastructure components (e.g., multi-core processors, computer networks and clusters), Google found it difficult to remain productive within this environment using these languages. Not only does Go's design focus on improving the productivity of developers/engineers, but Go's design incorporates the best features of C++, Java and Python into a single statically-typed, compiled, high-performance language: Using Go and a lightweight router library, such as chi , writing and launching a simple RESTful API service requires little time and effort, even if you have no experience with Go. chi 's compatibility with the Go standard library package net/http , optional subpackages (middleware, render and docgen) and consistent API allows you to compose mantainable, modular services that run fast. Plus, these services can be deployed to and thrive in a production environment . If you have previously built RESTful APIs using Node.js and a minimal web application framework, such as Express.js , then you will find this to be quite similar! Below, I'm going to show you: To install Go, visit the official Go downloads page and follow the instructions. If you want your machine to support multiple versions of Go, then I recommend installing GVM (Go Version Manager) . Note : This installation walkthrough will be for Mac OS X systems. Run the following command to install GVM to your machine: Either... A.) Close the current terminal window and open a new terminal window. Or... B.) Run the source command mentioned in the output to make the gvm executable available to the current terminal window. Run the following command to install the latest stable version of Go (as of 02/21, v1.16): Notice how the installation fails. The following error message is printed within the output: If we check the contents of the log file /Users/kenchan/.gvm/logs/go-go1.16-compile.log , then the actual cause of the failure will be shown: Because the go executable could not be found, and GVM assumes that this go executable should be Go v1.4, let's install Go v1.4 from binary: Apparently, there is an known issue with installing Go v1.4 on certain versions of Mac OS X. Instead, let's install Go v1.7.1 from binary: Then, set the go executable to Go v1.7.1: Set the environment variable $GOROOT_BOOTSTRAP to the root of this Go installation to build the new Go toolchain, which will provide the necessary tools to compile ( build ), format ( fmt ), run ( run ) source code, download and install packages/dependencies ( get ), etc.: Finally, let's install the latest stable version of Go and set the go executable to it: Note : The --default option sets this version of Go as the default version. Whenever you open a new terminal window and execute go version , this default version will be printed. Create a new project directory named "go-chi-restful-api": This RESTful API service will offer the following endpoints for accessing/manipulating "posts" resources: A post represents an online published piece of writing. It consists of a title, content, an ID and an ID of the user who authored the post: These endpoints will interface directly with JSONPlaceholder , a fake API for testing with dummy data. For example, when it receives a GET /posts request from a user, our Go RESTful API will check for this route and execute the route handler mapped to it. This route handler will send a request to https://jsonplaceholder.typicode.com/posts and pipe the response of that request back to the user. This project will be comprised of two Go files: Create these files within the root of the project directory: ( main.go ) A Go source file begins with a package clause. All source files within the same folder should have the same package name. main happens to be a special package name that declares the package outputs an executable rather than a library and has a main function defined within it. This main function is executed when we run the Go program. This program imports three standard library packages and one third-party package: Inside of the main function... ( posts.go ) This source file contains the sub-router for the /posts route and its sub-routes ( /posts/{id} ). Here, we import three standard library packages and one third-party package: An empty struct postsResources is defined to namespace all functionality related to "posts" resources. func (rs postsResource) Routes() chi.Router defines the Routes method on the struct postsResource . This method returns an instance of the chi router that handles the /posts route and its sub-routes. Recall previously how we attached this sub-router to the parent router in main.go : Note : A struct is a typed collection of fields. In this Routes function, several endpoints for /posts and its sub-routes are defined on this sub-router. Each method call on the r sub-router instance corresponds to a single endpoint: Along with the Routes function, each of these request handler functions is also defined on the struct postsResource . Let's explore the body of a request handler, List , to understand how request handlers work. When the user sends a GET request to /posts , the request handler for this endpoint sends a GET request to https://jsonplaceholder.typicode.com/posts via the http.Get method to fetch a list of posts. If an error is encountered while fetching this list of posts ( err is not nil ), then the http.Error method replies to the original request with the err object's message and a 500 status code ( http.StatusInternalServerError ). If the list is fetched successfully, then close the body of this response ( resp ) to avoid a resource leak. Set the "Content-Type" header of the response ( w , the one to send back to the user) to "application/json" since the posts data is in a JSON format. To extract the list of posts from resp , copy resp.Body to the w buffer with io.Copy , which uses a fixed 32 kB buffer to copy chunks of up to 32 kB at a time. Then, send this response with the retrieved posts back to the user. Once again, if an error is encountered, then reply to the original request with an error message and a 500 status code. Note : _ is commonly used to denote an unused variable. It serves as a placeholder. When sending a POST/PUT request to the RESTful API service, the body of this request can be accessed via r.Body . When the user sends a GET request to /posts/1 , the router must first pass the request through the PostCtx middleware handler. This middleware handler... In a request handler, values from the request's Context can be accessed by the value's corresponding key. So to get the URL parameter we extracted in the previous step and set as a Context value with the key id , call r.Context().Value("id") . Because both keys and values are of type interface{} in Context , cast this URL parameter value as a string . The http package provides shortcut methods for sending GET and POST requests via the Get and Post methods respectively. However, for PUT and DELETE requests, use the newRequest method to create these requests. You must explicitly pass the HTTP method to newRequest and manually add request headers. client.Do sends the HTTP request created by newRequest and returns an HTTP response. Once again, if an error is encountered, then reply to the original request with an error message and a 500 status code. We could have used io.ReadAll to extract the response body, like so... However, io.ReadAll is inefficient compared to io.Copy because it loads the entirety of the response body into memory. Therefore, if the service must handle a lot of users simultaneously, and the size of resp.Body is large (i.e. contents of a file), then it may run out of available memory and eventually crash. To run install RESTful API service, first install all required third-party dependencies. In this case, there is only one third-party dependency to install: github.com/go-chi/chi . Let's add the project's code to its own module using the following command: If you have previously worked with Node.js, then you can think of go.mod as Go's package.json . By having the project's code in its own module, the project's dependencies can now be tracked and managed. Run the following command to install the project's dependencies and generate a go.sum file that contains checksums of the modules that this project depends on: These checksums are used by Go to verify the integrity of the downloaded modules. If you have previously worked with Node.js, then you can think of go.mod as Go's package.json and go.sum as Go's package-lock.json . Run the following command to run the command: If you would like to run the service on a different port, then set the environment variable PORT to a different port number: Test the service by sending a POST request to /posts : It works! Try sending requests to the other endpoints. chi offers a lot of useful, pre-defined middleware handlers via its optional middleware package. Visit this link for a list of these middleware handlers. One such middleware handler is Logger , which prints on every incoming request: Let's import the github.com/go-chi/chi/middleware package and add the Logger middleware to main.go : ( main.go ) In a separate terminal tab/window, send the same POST request to /posts : Information about this request is logged to the terminal. Click here for a final version of the RESTful API. Try adding more routes to this RESTful API! JSONPlaceholder provides five other resources (comments, albums, photos, todos and users) that you can create endpoints for.

Testing plays a fundamental role in the development of quality software. Shipping and deploying software with undetected bugs and regressions opens up a can of terrible consequences such as losing the trust of end users or costing the business time and resources. In a large collaborative setting, having developers manually test each and every feature and user flow for bugs and regressions wastes valuable time that can be put towards improving other aspects of the software. As the codebase and team grows, this approach will not scale. By writing unit/integration/end-to-end tests, identifying and catching bugs and regressions throughout an entire codebase becomes a painless, automatable task that can easily be integrated into any continuous integration pipeline. Unlike most other languages, the Go programming language provides a built-in, standard library package for testing: testing . The testing package offers many utilities for automating the testing of Go source files. To write a test in Go, define a function with a name prefixed with Test (followed by a capitalized segment of text) and accepts an argument of struct type T , which contains methods for failing and skipping tests, running multiple tests in parallel, formatting test logs, etc. Example : This test checks whether the Sum function correctly calculates the sum of two integer numbers. If the sum does not match the expected value, then the test logs an error message and marks itself as having failed. Try it out in the Go Playground here . Below, I'm going to show you: Clone a copy of the Go and chi RESTful API from GitHub to your machine: This RESTful API specifies five endpoints for performing operations on posts: If you would like to learn how to build this RESTful API, then please visit this blog post . In the testless branch's version of the RESTful API, the posts.go file has been moved to a routes subdirectory, and the route handlers within this file have been refactored into a routes package to allow the testing of packages independent of the main package. Run the following command to install the project's dependencies: Note : If you run into installation issues, then verify that the version of Go running on your machine is v1.16 . To get started, let's create a posts_test.go file within the routes subdirectory. This file will contain tests for each of the route handlers within the posts.go file. Inside of posts.go , each endpoint is defined on the chi router via a corresponding routing method named as an HTTP method. To register the GET /posts endpoint on this router, call the .Get method with the route / (in main.go , this posts sub-router is attached to the main router along the /posts route). ( routes/posts.go ) rs.List ( rs refers to the PostsResource{} struct) is a route handler method defined on the PostsResource{} struct. It retrieves a list of posts from the JSONPlaceholder API: ( routes/posts.go ) Let's write a unit test , which tests a single unit of code (commonly a function), for the PostsResource{}.List route handler function. Start off with a simple failing test that will immediately fail and print the message "Not yet implemented." to the terminal: ( routes/posts_test.go ) To test all packages within the current working directory recursively... To test the route handler for GET /posts : Let's combine these code snippets together: ( routes/posts_test.go ) Run the test: Congrats! The route handler test passes! Notice how the TestGetPostsHandler takes approximately half a second to run due to the network request the PostsResource{}.List route handler sent to the JSONPlaceholder API. If the JSONPlaceholder API experiences heavy traffic or any server outages/downtime, then the network request may either take too long to send back a response or completely time out. Because our tests rely on the status of a third-party service, which we have no control over, our tests take much longer to finish running. Let's work on eliminating this unreliability factor from TestGetPostsHandler . PostsResource{}.List calls the GetPosts function, which sends this network request and pipes the response back into PostsResource{}.List if there was no network request error encountered. ( routes/posts.go ) Since the function responsible for sending the network request ( GetPosts ) is a package-scoped variable within the routes package, this function can be replaced with a mock function , which replaces the actual implementation of a function with one that simulates its behavior. Particularly, the network request will be simulated. As long as the mock function has the same function signature as the original function, calling the route handler in a test will remain the same. Inside of posts_test.go , add a mock function for GetPosts : ( posts_test.go ) This mock function creates some dummy data ( mockedPosts , which is a list containing one post), encodes this data as JSON via json.Marshal and returns a minimal HTTP response with a status code and body. These fields adhere to the http package's Response struct. At the top of the TestGetPostsHandler test, set the GetPosts package-scoped variable to this mock function and change the expectedTotal to 1 : Run the test: Wow! The mock allows our test to run much faster. Click here for a final version of the route handler unit test. Try writing tests for the other route handlers.