DEV Community: Dominic St-Pierre

Getting started with Go guide

Dominic St-Pierre — Mon, 24 Jul 2023 13:44:37 +0000

After 20 years in software development, you forget what it is to be a beginner. Reality hit hard, and I'm currently trying to get started on Erlang, and this experience inspired me to write this getting started guide for programmers that want to jump into Go.

Who you are

Maybe you're curious about Go, it's getting a lot of traction these days and is on a high trajectory.

Maybe you wrote some JavaScript either on the frontend or
backend and want to learn a new language.

Or you're like me, an enterprise programmer that mainly used C# and Java and at some point needed to get some excitement.

No matter this guide will help you pass this initial "what should I do next" phase when learning a new language.

What you probably already heard

If you asked around how to get started in Go, you most certainly were pointed to the following resources, which you should check before anything else.

Those will teach you the basics and concepts of Go and get familiar with its syntax. My guide assumes you took those because I'll focus on blockers that happen when you decide to create your first project without hand-holding, and
you're not sure on how to proceed.

No npm init or rails new

The first aspect I immediately loved about Go was the simplicity of files and directory structure when creating a new package. Coming from 15 years of C# and 3 years of Node, it was utterly refreshing to get cleaner directories with Go.

Packages are just directory, and this cannot be simpler. We'll create our first web server. For me, the first thing I try to create when learning a new language is some web API.

Since there's no tooling needed to create project and no specific directory structure enforce by the language, you cannot break anything. It's a considerable burden to remove for newcomers of a language. Don't worry about creating files at the right place and what not, you can change it later and create sub-package later.

We'll first create our main package. As you probably learn by now the main package can be executed as an OS process.

$> mkdir demo && cd demo

You can create this package anywhere on your file system. With the Go module, we don't need to bother with having a GOPATH environment variable anymore. The dependencies of your program are also using specific versions describe in the go.mod file.

Let's create our main file.

package main

import (
    "log"
    "net/http"
)

func main() {
    http.HandleFunc("/", home)
    log.Println(http.ListenAndServe(":8080", nil))
}

func home(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("hello world"))
}

We can now init our Go module files by running:

$> go mod init github.com/dstpierre/demo

Where github.com/dstpierre/demo is the module name. This step can be delayed but it makes things easier when it comes to dependencies management.

We've got a lot to talk about from this code sample. As someone who's learning Go, how could you write the code above? You can't unless you read the document or follow a tutorial from the internet.

The Go standard library has a lot to offer. Most often than not, you'll find a package in there that will do what you need. Here re some standard library
packages that you'll probably need on week one, and you should heck their documentation.

net/http: if you're going to write anything web related.
encoding: if you're going to manipulate data in JSON, XML, CSV etc.
io/ioutil: for easier IO helpers.
strings: for strings manipulation.
time: for time manipulation.

It's just a quick list that can get you very far, depending on what you're looking to build. What I'm trying to convey here is hat Go is probably the
most straightforward language available at the moment.

It's OK to not have sub-packages at first

Don't stress about having great packages on your first 2-3 projects. Here's something that could work for you if you're building or porting a line-of-business application.

Separate in a package your data access functionalities say a data package. Your main package can be a web server or a command-line program. At least you would have your data package reusable on other Go packages if you need to share the data access layer.

Eventually, you will most certainly create packages based on scope and domain. But if it's not clear at first or you're not comfortable, it's OK to have it ~wrong at first. It will not ruin your project I promise.

As you write more and more Go, you'll get used to the scope of packages and what they should expose and what not. At first, there are no good reasons to be blocked by this aspect. Refactoring the Go code is dead simple. Don't worry about getting it wrong or not having a package at first.

Packages and interfaces will come naturally after a couple of months writing Go code that does the work needed.

Write tests and document your code

Another beautiful aspect of Go is how fast the tests run. I'll encourage you to write tests as much as you can. Here are the packages that you should know about to get you started:

The httptest package is one of my favorite packages. Since I'm mainly building web applications, it's one of the most useful package for me. It allows you to test your web handlers. Here's an example testing our home function we wrote previously.

import (
    "io/ioutil"
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestHome(t *testing.T) {
    // this is the request that the browser would do
    req := httptest.NewRequest("GET", "http://localhost:8080/", nil)

    // this is the ResponseWriter our handler will write to
    rec := httptest.NewRecorder()

    // We execute our handler
    home(rec, req)

    // we get the body of the response
    resp := rec.Result()
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        t.Fatal(err)
    }
    defer resp.Body.Close()

    // assert that we have the correct response
    if resp.StatusCode != http.StatusOK {
        t.Errorf("expected status %d, got %d", http.StatusOK, resp.StatusCode)
    } else if string(body) != "hello world" {
        t.Errorf("expected body to be hello world, got %s", string(body))
    }
}

We can run our tests:

$> go test
PASS
ok      _/home/dstpierre/projects/osp/demo

One quick and nice option you can use for your test is the -cover argument which display the code coverage percentage by your tests.

$> go test -cover
PASS
coverage: 33.3% of statements
ok      _/home/dstpierre/projects/osp/demo

It takes discipline to have a good set of tests. I'm personally struggling with this every day. I mainly write code either for my own SaaS or for small companies that hired me as a consultant. Often the tests are skipped. They should not, and if you're able to take this habit of writing useful tests, your programs will be of higher quality and easier to maintain.

Another aspect that will help you with the long-term maintenance of your software is the built-in documentation of your packages. You may document your code as follow:

// DoSomething returns exactly the same value as the x
// parameter. You use it like this:
//
//  newX := DoSomething(5)
func DoSomething(x int) int {
  return x
}

You can look at doocumentation via go doc for instance:

$> go doc DoSomething
func DoSomething(x int) int
    DoSomething returns exactly the same value as the x parameter. You use it
    like this:

        newX := DoSomething(5)

Refer to this documentaiton to know more about how to document your ode.

Typical development flow

The development flow for writing Go programs is straightforward. Ideally, you would write the tests and write your code at the same time, so running the test is how you'd make sure your rogram works.

So it will be like this:

Write tests
Write the code needed to have the tests pass
Run the tests with go test -cover

You may skip the tests and run your program with:

$> go run main.go
$> go run .

You may build you program if it's not a library like this:

$> go build
$> ./executable-name

Where executable-name is the name of the binary built by go build.

Personally I prefer using make and Makefile.

build:
  go build

test:
  go test -cover

And I run:

$> make build
$> make test

I'm using Makefile because sooner or later there's more to add to the different steps. But that's not important at this stage.

What you want to do is have a program up and running and iterate from there—no need to install an auto-reload helper for now. Stop the execution of your program, modify the code, and re-run it. The goal is to add more complex workflows as you go gradually.

There's enough learning curve to get used to advance stuff
in Go like concurrency and interface. Leave the distraction aside nd focus on becoming used to the language and concept first.

After your first week writing Go code you are ready to read Effective Go.

Reading this will ensure you're writing idiomatic Go code and will level-up your understanding of the language.

You need to write and read Go code, there's the only way to get better.

Pick an open source project you like and try to contribute.
Start a side project and get better as you go.
Do not hesitate to read Go's standard library when you want to know host they did something.

Another great resource if you want to start using SQL databases is the Go database/sql tutorial.

From there, you'll have all the resources you should need to get you started. This guide does not show how to write Go code, and there are already too many resources for that. Instead, it tries to remove the road bump you might encounter during your first contact with writing Go code.

First deployment

As everything, deployment is a breeze in Go, you build a binary, and you push it to your server(s). You can even cross-compile from your OS to other supported OSes.

As you get more experience, you might want to use CI/CD to automate the deployment. This guide focus on the first month of getting started with Go. You don't need to add superfluous processes to deploy your first prototype. Keep it simple; it just works.

$> GOOS=linux GOARCH=amd64 go build

This build a binary for Linux 64-bit from either Mac or Windows. if you're already on Linux, you just go build.

I'll leave you explore the different options for deployment from here. This is a topic worth its own article I think.

On that note, I understand that leaving a comfortable language and stack to learn something new can be scary. In the last five years, I've learned Elm, Go, and now trying to get started with Erlang.

There's also a difference between lurking and playing a new language. For instance, I do have Rust and cargo installed on my Arch Linux. And from time to time, I do write the occasional functions. But deciding to write the next side project in a new language is challenging, I think Go is the easiest of all languages available to date.

Get started with React and StaticBackend

Dominic St-Pierre — Sun, 25 Jun 2023 10:56:00 +0000

StaticBackend is a simple backend server API you may use to build complex web applications. Fully open source and easy to self-host. It handles lot of backend building blocks.

GitHub repository: https://github.com/staticbackendhq/react-wiki

Let's see how we can use StaticBackend from a React application. In this tutorial, we will build a simple wiki web application.

Setup your development environment

You'll need to have a working development environment for StaticBackend and React to follow along.

StaticBackend

You have three options to get started with StaticBackend. It depends on your preferences.

Let's install the CLI for this example:

$ npm install -g @staticbackend/cli

This install a backend command you may use.

Start the dev server

$ backend server

This will create a backend application, an admin user and prints the keys you'll need.

You'll have an instance of StaticBackend running locally at http://localhost:8099.

Create the React app

We will use Create React App to create a new React application named react-wiki.

$ npx create-react-app react-wiki --template typescript
... lots of npm output ...
$ cd react-wiki

Test your app

Let's test that everything works so far before we jump into adding StaticBackend related functionalities. After that, you may start your application via this command:

$ npm start

You should see the default page created by create-react-app.

Add StaticBackend

We'll now add StaticBackend's JavaScript library to the React application.

$ npm install @staticbackend/js

We will create a reusable module that will expose the StaticBackend client to the rest of the React app.

Creating an instance of the client requires two essential arguments.

The public key tells StaticBackend which app to target.
The region indicates to the client which API URL to use.

Let's add those two configuration values inside the .env file.
create-react-app handles this file and make its variables available to your client-side application.

If you're working with multiple developers, they can all have their public key on their local development computer. So you'd only need to change those two values to go to production.

Let's create the .env file:

REACT_APP_SB_PUBLUC_KEY=dev_memory_pk
REACT_APP_SB_REGION=dev
REACT_APP_SB_ROOT_TOKEN=todo we don't need this

The variables must starts with REACT_APP_ to be available to your application via the process.env.REACT_APP_XYZ.

Make sure to change the values from the email printed to the terminal when you created your app.

We can now create our reusable module that initializes the StaticBackend JavaScript client.

src/sb.ts:

import {Backend} from "@staticbackend/js"

const pubKey = process.env.REACT_APP_SB_PUBLUC_KEY;
const region = process.env.REACT_APP_SB_REGION;

const bkn = new Backend(pubKey || "public key required", region || "dev");

export const backend = bkn;

Our JavaScript library exposes only one item, the Backend function. We use it to pass our public key and the region. From here, we will be able to import the client like this:

import {backend} from "./sb";

All available functions supported by StaticBackend are accessible via the backend instance.

User authentication

Our first step is to handle user authentication. We will use one page containing two forms, one for creating an account and one for letting the user log in.

Before we jump in, it might be helpful to understand how StaticBackend handles authentication and requests.

Users authenticate themselves in exchange for a session token. You need to supply this token for each request you send to StaticBackend.

It might be good to save this session token to the session storage. However, it expires after 12 hours.

src/auth.tsx:

import React, {Component} from "react";
import {backend} from "./sb";

export interface IProps {
  onToken: (token: string) => void;
}

interface IState {
  email: string;
  password: string;
}

export class Auth extends Component<IProps, IState> {
  constructor(props: IProps) {
    super(props);

    this.state = {
      email: "",
      password: ""
    }

  }

  onChanged(field: "email" | "password", e: React.ChangeEvent<HTMLInputElement>) {
    const val = e.currentTarget?.value;

    if (field == "email") {
      this.setState({
        ...this.state,
        email: e.target?.value,
      });
    } else {
      this.setState({
        ...this.state,
        password: e.target?.value
      });
    }
  }

  signup = async () => {
    const {email, password} = this.state;

    const res = await backend.register(email, password);
    if (!res.ok) {
      alert(res.content);
      return;
    }

    this.props.onToken(res.content);
  }

  signin = async () => {
    const {email, password} = this.state;

    const res = await backend.login(email, password);
    if (!res.ok) {
      alert(res.content);
      return;
    }

    this.props.onToken(res.content);    
  }

  render() {
    return (
      <div>
        <h1>User authentication</h1>
        <div>
          <label>Email</label><br />
          <input type="email" required value={this.state.email} onChange={this.onChanged.bind(this, "email")} />
        </div>

        <div>
          <label>Password</label><br />
          <input type="password" required value={this.state.password} onChange={this.onChanged.bind(this, "password")} />
        </div>

        <div>
          <button onClick={this.signup.bind(this)}>Create account</button> 
          <button onClick={this.signin.bind(this)}>Login</button>
        </div>
      </div>
    );
  }
}

The main code that's not React boilerplate is the two functions related to authentication signup and signin. We pass the email and password to create an account or authenticate the user.

Notice how we're using an async/await function to call StaticBackend endpoints.

We're using a callback function from the props to send the user's session token back to the parent.

The following changes were made to the app.tsx file.

src/app.tsx:

import React from 'react';
import logo from './logo.svg';
import './App.css';

import {Auth} from "./auth";

interface IState {
  token: string | null;
}

export class App extends React.Component<any, IState> {
  constructor(props: any) {
    super(props);

    this.state = {
      token: null
    }    
  }

  onToken(token: string) {
    this.setState({token: token});
  }

  render() {
    if (!this.state.token) {
      return <Auth onToken={this.onToken.bind(this)} />;
    }

    return (
      <div>
        <h1>Todo</h1>
      </div>
    )
  }
}

If we have no session token, we display our Auth component. Otherwise, we show a simple to-do text for now.

Wiki article CRUD

The core functionality of StaticBackend is its database. Let's see how teams manage a wiki by creating, retrieving, updating, and deleting rticles.

Create and save article

Let's create a simple component to create and edit articles. When we create an article, we'll ask for the author's name, the title, and the body content.

When we are in edit mode, only the content will be editable.

We cannot build it with the default security model By default, users of the same account have read permission but cannot modify a record created by another user of the same account. Only the document owner has the write permission using the default security model.

We want users of the same account to have write permission for an article created across their team members for our wiki.

Custom permissions are set using a suffix of the table name. In our case, we will use articles_770_ instead of articles to let users of the same account update documents created for their account.

We will use articles_770_ which means:

7: The owner has read/write permissions.
7: The account users have read/write permissions.
0: Other logged-in users has no permissions.

Note that the default permission are::

7: The owner has read/write.
4: Users of same account has read permission.
0: Other logged-in users has no permissions.

src/article_edit.tsx:

import React, { FormEventHandler } from "react";
import { backend } from "./sb";

export interface IProps {
  token: string;
  editId: string | null;
  onSave: (article: Article) => void;
}

interface IState {
  article: Article;
  isNew: boolean;
}

export class ArticleEdit extends React.Component<IProps, IState> {
  constructor(props: IProps) {
    super(props);

    this.state = {
      article: {
        id: "",
        accountId: "",
        title: "",
        body: "",
        authorName: "",
        created: new Date()
      },
      isNew: props.editId == null
    }
  }

  componentDidMount = async () => {
    if (this.props.editId) {
      const res = await backend.getById(
        this.props.token,
        "articles_770_",
        this.props.editId
      );
      if (!res.ok) {
        alert(res.content);
        return;
      }

      this.setState({
        article: res.content,
        isNew: false
      })
    }
  }

  onChanged(field: "title" | "body" | "authorName", e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) {
    const val = e.currentTarget?.value;
    let { article } = this.state;

    article[field] = val;

    this.setState({
      ...this.state,
      article: article,
    });
  }

  save = async (e: any) => {
    e.preventDefault();

    const {token, editId, onSave} = this.props;
    const {isNew, article} = this.state;

    let res = null;
    if (isNew) {
      article.created = new Date();

      res = await backend.create(
        token,
        "articles_770_",
        article
      )
    } else {
      res = await backend.update(
        token,
        "articles_770_",
        editId || "",
        article
      )
    }

    if (!res.ok) {
      alert(res.content);
      return;
    }

    this.props.onSave(res.content);
  }

  renderAuthor() {
    if (this.state.isNew) {
      return (
        <p>
        <input
          type="text"
          value={this.state.article.authorName}
          onChange={this.onChanged.bind(this, "authorName")}
          placeholder="Author name"
          required
        />
        </p>
      )
    } else {
      <p>{this.state.article.authorName}</p>
    }
  }

  render() {
    const { article, isNew } = this.state;

    return (
      <div>
        <h1>{isNew ? "Create new article" : `Editing ${article.title}`}</h1>
        <form onSubmit={this.save.bind(this)}>
          <p>
          <input
            type="text"
            value={article.title}
            onChange={this.onChanged.bind(this, "title")}
            placeholder="Article title"
          />
          </p>
          <p>
          <textarea 
            value={article.body}
            onChange={this.onChanged.bind(this, "body")}>
          </textarea>
          </p>
          {this.renderAuthor()}
          <p>
          <button type="submit">
            {isNew ? "Create article" : "Save changes"}
          </button>
          </p>
        </form>
      </div>
    )
  }
}

The things that you should focus on are:

This component receives its token and an indicator if we're editing or creating a new article.

export interface IProps {
  token: string;
  editId: string | null;
  onSave: (article: Article) => void;
}

The state and constructor are straightforward.

Let's look at the componentDidMount where we use the getById function to grab the article via the id received in the props.

const res = await backend.getById(
  this.props.token,
  "articles_770_",
  this.props.editId
);

The save function make sure to call the create or update function depending if we're creating or updating the article.

Once saved, we call the onSave function received in the props and return the control to the parent component.

List and delete article

There have been some changes to the src/app.tsx file to list, react to the creation and update, and delete articles.

Here's the part that have changed:

The state:

interface IState {
  token: string | null;
  articles: Array<Article>;
  isEditing: boolean;
  editId: string | null;
}

The callback after a successful account creation or login now fetches the articles for that account.

onToken(token: string) {
    this.setState({
      ...this.state,
      token: token
    });

    (async () => {
      const res = await backend.list(
        token,
        "articles_770_"
      );
      if (!res.ok) {
        console.error(res.content);
        return;
      }

      let articles = res.content.results;
      if (!articles) {
        articles = [];
      }

      this.setState({
        ...this.state,
        articles: articles
      })
    })();
  }

When an article is created or updated we handle the changes in a callback we pass via props to the ArticleEdit component.

onArticleSaved(article: Article) {
  let { articles, editId } = this.state;

  if (editId == null) {
    articles.push(article);
  } else {
    let idx = this.findArticle(articles, editId);
    if (idx > -1) {
      articles[idx] = article;
    }
  }

  this.setState({
    ...this.state,
    articles: articles,
    isEditing: false,
    editId: null
  })
}

Thie is the deletion of an article:

del = async (id: string) => {
  const res = await backend.delete(
    this.state.token || "",
    "articles_770_",
    id || ""
  );
  if (!res.ok) {
    alert(res.content);
    return;
  }

  let { articles } = this.state;

  let idx = this.findArticle(articles, id);
  if (idx > -1) {
    articles.splice(idx, 1);
  }

  this.setState({
    ...this.state,
    articles: articles
  })
}

The render function:

render() {
  if (!this.state.token) {
    return <Auth onToken={this.onToken.bind(this)} />;
  } else if (this.state.isEditing) {
    return <ArticleEdit
      token={this.state.token}
      editId={this.state.editId}
      onSave={this.onArticleSaved.bind(this)}
    />;
  }

  return (
    <div>
      <h1>List articles</h1>
      <button onClick={this.newArticle.bind(this)}>
        Create a new article
      </button>
      <p>
        <strong>Todo list articles</strong>
      </p>
      <ul>
        {this.state.articles.map((a) => this.renderArticle(a))}
      </ul>
    </div>
  )
}

Notice how we're passing the callback to the ArticleEdit's onSave props.

Finally, the renderArticle which render a simple <li> with the Edit and Delete buttons.

renderArticle(a: Article) {
  return (
    <li key={a.id}>
      <h4>{a.title}</h4>
      <p>{a.body}</p>
      <p>By {a.authorName} on {a.created}</p>
      <p>
        <button onClick={this.edit.bind(this, a.id)}>Edit</button>
        <button onClick={this.del.bind(this, a.id)}>Delete</button>
      </p>
    </li>
  )
}

Conclusion

The concept should look familiar if you have built a React application in the past. You may use all the functionalities of StaticBackend via the
backend client.

In this tutorial, we've only covered the authentication and the
database, but there are many more building blocks at your disposal.

WebSocket - real-time database and topic-based communication. It's not limited to database events.
Storage - upload files and serve them via a CDN close to your users location.
Server-side functions - create secure function when you need to run things server-side.
Send emails - all web/mobile apps need to send emails to their users.
Cache - cache key data for performance.