Forem: Orlando Monteverde

API Rest con Go (Golang) y PostgreSQL Parte 5

Orlando Monteverde — Mon, 24 Aug 2020 15:19:56 +0000

Requisitos:

Conocimientos básicos sobre el lenguaje go.
Conocimiento sobre HTTP y REST recomendable.
Go en su versión 1.11 o superior.
PostgreSQL en su versión 9.6 o superior.
Conocimientos básicos de SQL deseables.
Ganas de aprender.

Que vamos a desarrollar

Crearemos un API Rest para un microblog, estilo twitter en su versión mas básica. Con un modelo de usuarios y uno de publicaciones. Con un CRUD completo en cada caso, autenticación con JSON Web Tokens, creación, uso de middlewares y asegurar contraseña por con bcrypt. ¿Suena interesante? ¡Entonces vamos!

Indice

Código fuente hasta el momento.

Activando el API

Lo primero que debemos hacer es asegurarnos de que el API esta corriendo.

go build ./cmd/microblog && ./microblog

Realizando peticiones

Cuando desarrollamos un API REST nuestro interés, por lo general, es que sea consumida por algún cliente, bien sea una aplicación móvil, web, otro servidor, entre otros. Pero no podemos esperar hasta conectar el cliente para saber si todo funciona como esperamos, para eso existen las pruebas. Hay diferentes tipos de pruebas, y es un tema que excede el propósito de este articulo, en esta ocasión probaremos cada endpoint manualmente con un par de herramientas populares para dicho fin: curl y postman.

La intención es la siguiente: muestro como realizar la petición con postman por medio de un GIF y posteriormente les comparto como hacer la misma petición desde la terminal usando curl, no es necesario que utilicen ambos, el uso de estos programas no sera cubierto a detalle pero si lo suficiente para las necesidades de nuestro proyecto. Dicho esto, manos a la obra.

Creando un usuario

Si vamos a utilizar postman necesitamos tenerlo instalado en nuestro ordenador, si no es así podemos descargarlo desde aquí.

Lo primero que haremos sera crear una colección en postman, este paso no es obligatorio pero nos va a facilita reutilizar las peticiones luego.

Ahora podemos proceder a crear nuestro usuario, simplemente realizando una petición de tipo POST a la dirección http://localhost:9000/api/v1/users/ con el contenido correspondiente en formato JSON.

O por medio de curl.

curl -X POST -H 'Content-Type: application/json' \
  -d '{"first_name": "orlando", "last_name": "monteverde", "username": "orlmonteverde", "email": "orlmonteverde@gmail.com", "password": "123456"}' \
  http://localhost:9000/api/v1/users/

En cualquier caso habremos registrado un nuevo usuario. Ahora que ya sabemos como se hace, los invito a insertar un par mas, como practica y para poder usarlos en las siguientes pruebas.

Obtener todos los usuarios

De manera similar a la caso anterior vamos a realizar una petición a la dirección http://localhost:9000/api/v1/users/ pero esta vez sera de tipo GET y no requiere contenido.

O con curl.

curl http://localhost:9000/api/v1/users/

Obtener un usuario

En el caso anterior pudimos obtener todos los usuarios, pero esta vez queremos obtener uno en especifico, esto lo logramos repitiendo la petición pero esta vez agregando el id del usuario al final de la dirección http://localhost:9000/api/v1/users/{id}.

O con curl.

curl http://localhost:9000/api/v1/users/11

Actualizar usuario

Ahora que ya podemos crear y obtener usuarios, veamos como actualizar un usuario existente. Esta vez realizamos una petición PUT a la dirección http://localhost:9000/api/v1/users/{id}, donde el id debe corresponder con el del usuario que deseamos actualizar. Y, finalmente, el contenido que reemplazara al anterior en formato JSON.

O con curl.

curl -X PUT -H 'Content-Type: application/json' \
  -d '{"email": "orlmonteverde@gmail.com", "first_name": "carlos", "last_name": "monteverde"}' \
  http://localhost:9000/api/v1/users/11

Eliminar usuario

Para completa nuestro CRUD solo faltaria la operación de borrar. Realizamos una petición DELETE a la dirección http://localhost:9000/api/v1/users/{id}, donde el id debe corresponder con el del usuario que deseamos borrar y con eso es suficiente.

O con curl.

curl -X DELETE http://localhost:9000/api/v1/users/11

Llegados a este punto, ya tenemos experiencia realizando peticiones a nuestra API así que, como es costumbre, para el caso de las publicaciones avanzaremos mas rápido ya que las operaciones son bastante parecidas.

Crear publicación

curl -X POST -H 'Content-Type: application/json' \
  -d '{"body": "my first post", "user_id": 14}' \
  http://localhost:9000/api/v1/posts/

Es importante recordar que el user_id debe coincidir con el id de un usuario existente u obtendremos un error debido a la restricción que agregamos al momento de crear la tabla en la parte 3.

Obtener todas las publicaciones

curl http://localhost:9000/api/v1/posts/

Obtener una publicación

curl http://localhost:9000/api/v1/posts/11

Actualizar publicación

curl -X PUT -H 'Content-Type: application/json' \
  -d '{"body": "my first post updated"}' \
  http://localhost:9000/api/v1/posts/1

Borrar una publicación

curl -X DELETE http://localhost:9000/api/v1/posts/10

Obtener publicaciones por usuario

curl -X GET http://localhost:9000/api/v1/posts/user/14

Middleware

Sin complicarlo demasiado, un middleware en nuestro caso es solo una función, esta ejecutara alguna acción antes (o después) de que se ejecute una función handler, esto nos permite reutilizar código de una manera bastante practica, por ejemplo, obtener logs por consola en cada petición, recuperar el programa después de que ocurra un panic para evitar que nuestro servidor caiga y, prácticamente, cualquier cosa que se nos ocurra. Conociendo la firma que deben tener estas funciones, el proceso que tenga lugar en el cuerpo de la función lo definimos nosotros.

Los middlewares son tan usados que el paquete chi (y similares) que estamos ocupando para manejar las rutas incluye varios métodos para trabajar con ellos, ademas de incluir sus propios middlewares, vamos a utilizar dos que son bastante utilizados.

Middlewares con Chi

Regresamos al paquete server y realizamos unos cambios en el archivo server.go.

// internal/server/server.go
package server

import (
    "log"
    "net/http"
    "time"

    "github.com/go-chi/chi"
    "github.com/go-chi/chi/middleware"
    v1 "github.com/orlmonteverde/go-postgres-microblog/internal/server/v1"
)

// [...]

Importando el paquete middleware, que es un subpaquete de chi y procedemos a usarlo.

// internal/server/server.go
// [...]
func New(port string) (*Server, error) {
    r := chi.NewRouter()

    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)

    // [...]
}

// [...]

Ahora, gracias al método Use del puntero a chi.Mux, podemos agregar middlewares a las rutas hijas de r, en este caso Logger, que nos muestra logs por consola de las peticiones a nuestra API, los invito a realizar y petición y observar la terminal donde tienen corriendo el API, por ejemplo, esta:

curl http://localhost:9000/api/v1/users/

De igual forma, agregamos el middleware Recoverer, que permite a nuestro servidor recuperarse de posibles panics. El paquete chi nos permite agregar middlewares a rutas especificas por medio del método With del puntero a chi.Mux de a siguiente manera:

r.With(middleware).Get("/", handler)

Esto lo vamos a utilizar mas adelante cuando desarrollemos nuestro middleware para autorización con JWT.

JSON Web Token

Hasta este punto tenemos un API funcional con las operaciones mas comunes, pero se encuentra totalmente expuesta, normalmente deseamos que solo un grupo determinado pueda acceder a cierta información y aun mas si hablamos de editar o borrar.

Para solucionar esto normalmente recurrimos a la autorización, donde tenemos varias opciones. Una bastante utilizada con las API REST es JWT, les aseguro que la menciono por eso y no porque tengo como cuatro artículos diciendo que lo usaríamos 😅.

JWT es un estándar abierto basado en JSON propuesto por IETF (RFC 7519) para la creación de tokens de acceso que permiten la propagación de identidad y privilegios o claims en inglés. Por ejemplo, un servidor podría generar un token indicando que el usuario tiene privilegios de administrador y proporcionarlo a un cliente. El cliente entonces podría utilizar el token para probar que está actuando como un administrador en el cliente o en otro sistema. El token está firmado por la clave del servidor, así que el cliente y el servidor son ambos capaz de verificar que el token es legítimo.
wikipedia

Lo primero que necesitamos es descargar un paquete de terceros que nos facilitara el trabajo con JWT, existen varios, pero personalmente me gusta jwt-go, así que procederemos con la descarga.

go get github.com/dgrijalva/jwt-go

Paquete Claim

La información contenida dentro de nuestro token es lo que llamamos claims, aquí podemos agregar información útil, algunas estandarizadas como la fecha de expiración del token y también datos personalizados que nos interese incluir, por ejemplo si tiene permisos de administrador. No debemos agregar aquí información sensible/secreta como contraseñas o números de tarjeta de crédito porque esta información sera compartida en base64, por lo que es fácilmente decodificable, en un momento lo veremos.

Vamos a colocar toda la lógica de los claims en un paquete para facilitar el trabajo con los mismos.

// pkg/claim/claim.go
package claim

import jwt "github.com/dgrijalva/jwt-go"

type Claim struct {
    jwt.StandardClaims
    ID string `json:"id"`
}

Creamos un estructura a la que llamamos Claim y le agregamos el tipo StandardClaims que nos proporciona el paquete jwt-go, este tipo incluye los campos mas comunes para el token, adicionalmente incluimos el campo ID que utilizaremos para agregar el id del usuario, aunque podemos agregar todos los campos que necesitemos es mejor no excederse ya que mientras mas contenido incluyamos mayor sera el tamaño del token.

Ahora agreguemos un método al nuestro tipo Claim que nos permita generar un token a partir de este.

// pkg/claim/claim.go
func (c *Claim) GetToken(signingString string) (string, error) {
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, c)
    return token.SignedString([]byte(signingString))
}

Esta es una tarea bastante sencilla gracias al paquete jwt-go, utilizando su función NewWithClaims podemos obtener un token que incluya un claim, ademas debemos pasar el método que queremos utilizar para firmar el token, en este caso HS256 que es bastante utilizado pero existen mas, los invito a revisar la documentación del paquete jwt-go y la de JWT.

Finalmente firmamos el token con el método SignedString del puntero a jwt.Token, este método requiere la clave que utilizaremos para firmar el token y, aunque el tipo esperado por esta es una interfaz vacía (interface{}) no podemos utilizar una clave de tipo string directamente, sino que debemos pasarlo como un slice de bytes.

Agreguemos una función mas, que nos permita hacer la operación inversa, recibir un token, validarlo y retornar un Claim a partir de este.

// pkg/claim/claim.go
func GetFromToken(tokenString, signingString string) (*Claim, error) {
    token, err := jwt.Parse(tokenString, func(*jwt.Token) (interface{}, error) {
        return []byte(signingString), nil
    })
    if err != nil {
        return nil, err
    }

    if !token.Valid {
        return nil, errors.New("invalid token")
    }

    claim, ok := token.Claims.(jwt.MapClaims)
    if !ok {
        return nil, errors.New("invalid claim")
    }

    iID, ok := claim["id"]
    if !ok {
        return nil, errors.New("user id not found")
    }

        d, ok := iID.(float64)
    if !ok {
        return nil, errors.New("invalid user id")
    }

    return &Claim{ID: int(id)}, nil
}

La función GetFromToken es un poco extensa pero no muy compleja, lo mas importante es el comienzo, donde utilizamos la función Parse del paquete jwt-go para validar el token y retornar un puntero a jwt.Token por medio de una función de tipo jwt.Keyfunc con la firma func(*jwt.Token) (interface{}, error) que debe retornar la clave para descifrar el token que, en este caso, debe ser la misma que usamos para firmarlo anteriormente porque estamos utilizando criptografía simétrica.

Hecho esto, realizamos algunas validaciones: si el método Parse retorno un error, si el token obtenido es valido, realizamos un type assertion al Claim dentro del token para convertirlo en un jwt.MapClaims que internamente es solo un map[string]interface{}, confirmamos si contiene la clave id, correspondiente al campo ID en nuestro tipo Claim, realizamos un type assertion para obtener el id como un float64 y retornar un puntero al tipo Claim con el id obtenido.

Middleware de autorización

Con esto terminamos el paquete claim, es momento de crear nuestro middleware. Comencemos por crear un nuevo directorio al que llamaremos middleware dentro del directorio internal.

mkdir internal/middleware

Dentro de este directorio crearemos un archivo al que llamaremos auth.go (o el nombre que prefieran) y agregamos el siguiente contenido.

// internal/middleware/auth.go
package middleware

import (
    "errors"
    "strings"
)

func tokenFromAuthorization(authorization string) (string, error) {
    if authorization == "" {
        return "", errors.New("autorization is required")
    }

    if !strings.HasPrefix(authorization, "Bearer") {
        return "", errors.New("invalid autorization format")
    }

    l := strings.Split(authorization, " ")
    if len(l) != 2 {
        return "", errors.New("invalid autorization format")
    }

    return l[1], nil
}

La función tokenFromAuthorization no es obligatoria, pero nos permite extraer parte de la lógica del middleware, que crearemos a continuación, dejando el código mas limpio. Esta función espera recibir una cadena de texto a la que llamamos authorization con una forma similar a esta Bearer <TOKEN>, validamos que el formato sea correcto: que no sea una cadena de texto vaciá, que contenga el prefijo Bearer gracias a la función HasPrefix del paquete strings, separamos la cadena de texto con la función Split también del paquete strings utilizando como separador el espacio que divide el prefijo Bearer del token, confirmamos que el slice obtenido tenga exactamente dos elementos y, si todo marcha como esperamos, retornamos el segundo elemento del slice, el cual debería corresponder al token.

Suficiente preparación, es momento crear nuestro middleware de autorización.

// internal/middleware/auth.go
package middleware

import (
    "context"
    "errors"
    "net/http"
    "os"
    "strings"

    "github.com/orlmonteverde/go-postgres-microblog/pkg/claim"
    "github.com/orlmonteverde/go-postgres-microblog/pkg/response"
)

func Authorizator(next http.Handler) http.Handler {
    signingString := os.Getenv("SIGNING_STRING")
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        authorization := r.Header.Get("Authorization")
        tokenString, err := tokenFromAuthorization(authorization)
        if err != nil {
            response.HTTPError(w, r, http.StatusUnauthorized, err.Error())
            return
        }

        c, err := claim.GetFromToken(tokenString, signingString)
        if err != nil {
            response.HTTPError(w, r, http.StatusUnauthorized, err.Error())
            return
        }

        ctx := r.Context()
        ctx = context.WithValue(ctx, "id", c.ID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// [...]

Vamos a recorrer la función paso a paso. Al inicio estamos obteniendo el valor de la variable de entorno SIGNING_STRING por medio de la función Getenv del paquete os y posteriormente estamos retornando una función, esta función tiene la misma estructura de las funciones handler que hemos utilizado anteriormente, pero no podemos retornarla como una función literal, sino que la convertimos al tipo HandlerFunc del paquete http, el cual satisface la interface Handler.

Dentro de esta función realizamos todo el proceso de validación del token, obtenemos el contenido del Header Authorization, que es la manera en la que esperamos recibir el token, y utilizamos la función tokenFromAuthorization que creamos recientemente para extraer el token, comprobamos si existe un error y utilizamos la función HTTPError del paquete response para responder con un mensaje de error de igual forma a como lo hacemos en las funciones handler seguido de un return para que la función no se continúe ejecutando.

Ahora utilizamos la función GetFromToken que agregamos antes al paquete claim, y obtenemos un nuevo Claim a partir del token, confirmamos si existe un error de manera similar al caso anterior. Superado este punto podemos asumir que todo ha marchado bien y el token es valido, así que permitiremos que la solicitud pase al handler correspondiente, representado en el middleware como el argumento next, llamando a su método ServeHTTP y pasando el http.ResponseWriter y el puntero a http.Request.

Pero si son observadores notaran que estamos haciendo un par de cosas antes, a partir del contexto del puntero a http.Request, creamos un nuevo contexto con la función WithValue del paquete context al que pasamos el ID del usuario utilizando como clave la cadena de texto id y pasamos al método ServeHTTP el puntero a http.Request con este nuevo contexto. Esto ultimo no es obligatorio y no usaremos ese valor en este caso, es principalmente para mostrar que pueden pasar valores al handler utilizando el contexto, cosa que puede resultar bastante útil.

Utilizando el Middleware de autorización

Una vez que tenemos listo nuestro middleware de autorización es momento de utilizarlo, así que vamos a regresar al archivo user_router.go para hacer algunos cambios.

// internal/server/v1/user_router.go
package v1

import (
    // [...]
    "github.com/orlmonteverde/go-postgres-microblog/internal/middleware"
    // [...]
)

// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.
        With(middleware.Authorizator).
        Get("/", ur.GetAllHandler)

    // [...]

    return r
}

Utilizamos el método With del tipo puntero a chi.Mux para pasar un middleware en linea a una ruta especifica y es suficiente, nuestro endpoint para obtener usuarios se encuentra protegida, vamos a probarlo.

curl http://localhost:9000/api/v1/users/

Si todo ha salido bien, deberíamos obtener una respuesta como la siguiente.

{
  "message": "autorization is required"
}

Perfecto, ahora nuestra ruta esta protegida con JWT y podemos agregar nuestro nuevo middleware a todas las rutas que nos interese proteger utiliozando cualquiera de las opciones que nos ofrece chi para manejar middlewares.

Login

Hasta este punto nuestra API funciona bastante bien, pero no tenemos forma de acceder a las rutas protegidas por el middleware Authorizator, necesitamos una manera de confirmar la identidad del usuario y darle permiso de acceder a esa información, así que vamos a crear un nuevo endpoint, para permitir al usuario hacer login.

Regresaremos al archivo user_router.go para realizar algunas modificaciones y agregar nuestro nuevo handler.

// internal/server/v1/user_router.go
package v1

// [...]
func (ur *UserRouter) LoginHandler(w http.ResponseWriter, r *http.Request) {
    var u user.User
    err := json.NewDecoder(r.Body).Decode(&u)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    defer r.Body.Close()

    ctx := r.Context()
    storedUser, err := ur.Repository.GetByUsername(ctx, u.Username)
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    if !storedUser.PasswordMatch(u.Password) {
        response.HTTPError(w, r, http.StatusBadRequest, "password don't match")
        return
    }

    c := claim.Claim{ID: int(storedUser.ID)}
    token, err := c.GetToken(os.Getenv("SIGNING_STRING"))
    if err != nil {
        response.HTTPError(w, r, http.StatusInternalServerError, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"token": token})
}

// […]

Como en los pasos anteriores hemos preparado el terreno para este endpoint el resultado es bastante sencillo y no creo que requiera demasiada explicación, pero igual le daremos un repaso rápido.

Obtenemos el usuario que debe ser enviando en el cuerpo de la petición, el cual debe contener el username y la password, buscamos un usuario en nuestra base de datos con el username enviado, utilizando el método GetByUsername del Repository.

Si el usuario existe procedemos a confirmar que la contraseña enviada coincida con la que tenemos almacenada en nuestra base de datos gracias al método PasswordMatch que agregamos a nuestro tipo User.

Si la contraseña coincide generamos un nuevo Claim, obtenemos un nuevo token a partir de este, utilizando su método GetToken, con el misma firma que utilizamos para el desencriptado del token en el middleware.

Si todo ha sucedido correctamente retornamos el nuevo token y podemos usar este para acceder a la información protegida por el middleware Authorizator. Vamos a probar el nuevo endpoint.

Ahora debemos agregar nuestro nuevo handler a las rutas para poder utilizarlo.

// internal/server/v1/user_router.go
package v1

// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    // [...]

    r.Post("/login/", ur.LoginHandler)

    return r
}

Y ahora podemos realizar peticiones para probar nuestro handler.

curl -X POST http://localhost:9000/api/v1/users/login/ \
    -H 'Content-Type: application/json' \
    -d '{"username": "orlmonteverde", "password": "123456"}'

Con esto obtendremos un nuevo token y podremos usarlo en las peticiones protegidas. Por cierto, no se lo digan a nadie, pero esas son mis credenciales en facebook 😏.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTV9.Dd0Ej44-4P2xwZAf9sXKUUInyRJ71QNVYRJaHCxj1FE"
}

Ahora tenemos nuestro token, como mencione antes, la información contenida en este es fácilmente decodificable, podemos comprobar esto si vamos a jwt.io y pegamos nuestro token.

Para finalizar, vamos a probar nuestro token contra el endpoint protegido con el middleware.

curl http://localhost:9000/api/v1/users/ \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTV9.Dd0Ej44-4P2xwZAf9sXKUUInyRJ71QNVYRJaHCxj1FE'

Ahora deberíamos poder acceder a la información como antes de agregar el middleware. Si tienes algun problema o deseas ver el codigo completo, se encuentra disponible en este repositorio.

Gracias por acompañarme en este tutorial y por la paciencia, me tarde un montón, lo siento por eso.

Realmente espero que el contenido les sea de utilidad, y cualquier duda o sugerencia, por favor, déjenla en los comentarios y les responderé tan pronto como me resulte posible. Saludos y gracias por leer 😏.

API Rest con Go (Golang) y PostgreSQL Parte 4

Orlando Monteverde — Thu, 04 Jun 2020 06:17:12 +0000

Requisitos:

Conocimientos básicos sobre el lenguaje go.
Conocimiento sobre HTTP y REST recomendable.
Go en su versión 1.11 o superior.
PostgreSQL en su versión 9.6 o superior.
Conocimientos básicos de SQL deseables.
Ganas de aprender.

Que vamos a desarrollar

Indice

Código fuente hasta el momento.

El paquete response

Comencemos creando un nuevo paquete al que llamaremos response, en este agruparemos algunas funcionalidades útiles para las respuestas de nuestras funciones handler, podríamos utilizar, por ejemplo el paquete render perteneciente al ecosistema de chi, que es el paquete que estamos utilizando para manejar las rutas, o algún equivalente, pero en nuestro caso no seria necesario descargar una dependencia adicional si perfectamente podemos cubrir nuestra necesidad con unas pocas lineas de código. Dicho esto, vamos a crear nuestro nuevo paquete.

mkdir pkg/response && touch $_/response.go

Y agregamos el siguiente contenido a nuestro paquete.

// pkg/response/response.go
package response

type ErrorMessage struct {
    Message string `json:"message"`
}

Con este tipo, ErrorMessage podemos estandarizar las respuestas de error, solo contiene un campo Message de tipo string que representa el mensaje de error.

// pkg/response/response.go
// [...]

type Map map[string]interface{}

Map es simplemente un map con claves de tipo string y valor de interface vacía, que, a efectos prácticos nos permite almacenar valores de cualquier tipo. Este tipo nos facilita el trabajo de serializar/deserializar, lo veremos en la practica en breve.

// pkg/response/response.go
// [...]

func JSON(w http.ResponseWriter, r *http.Request, statusCode int, data interface{}) error {
    if data == nil {
        w.Header().Set("Content-Type", "application/json; charset=utf-8")
        w.WriteHeader(statusCode)
        return nil
    }

    j, err := json.Marshal(data)
    if err != nil {
        return err
    }

    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(statusCode)
    w.Write(j)
    return nil
}

Con la función JSON podemos realizar respuestas en formato JSON, evitando repetir constantemente la parte de serializar la data, y sinceramente lo vamos a ocupar bastante 😜. En caso de que el argumento data sea diferente de nil lo serializamos como JSON y lo escribimos en la respuesta.

// pkg/response/response.go
// [...]

func HTTPError(w http.ResponseWriter, r *http.Request, statusCode int, message string) error {
    msg := ErrorMessage{
        Message: message,
    }

    return JSON(w, r, statusCode, msg)
}

En lo que respecta a la función HTTPError es solo una manera conveniente de crear un nuevo ErrorMessage a partir del message que recibe y luego enviarlo como respuesta JSON gracias a la función JSON que creamos antes.

Si algo de lo anterior no les ha quedado claro estoy seguro de que sera mas fácil de entender cuando lo veamos en acción, cosa que haremos de inmediato. Es momento de mi parte favorita, manejar las peticiones 😁.

Manejar las peticiones

Si recuerdan en el primer articulo creamos el paquete server (internal/server), en el que dejamos listas algunas configuraciones, ahora es momento de regresar a ese paquete y agregar nuestros handlers.

Para comenzar vamos a crear un paquete al que llamaremos v1 dentro del paquete server, es decir, sera una carpeta dentro de este ultimo. No es realmente necesario trabajar los handlers en un paquete separado de server, pero si a futuro debemos agregar una nueva versión de nuestra API sera mas conveniente tenerlo organizado de esta forma. Pero esa es solo mi opinión y no la verdad absoluta, siéntanse libres de probar, buscar y compartir cualquier otra opción o idea al respecto.

mkdir internal/server/v1

Rutas de usuario

En primer lugar crearemos un nuevo archivo dentro del directorio v1 que creamos recientemente, a este archivo lo llamaremos user_router.go.

touch internal/server/v1/user_router.go

Y agregamos en este nuevo archivo el siguiente contenido.

// internal/server/v1/user_router.go
package v1

import "github.com/orlmonteverde/go-postgres-microblog/pkg/user"

type UserRouter struct {
    Repository user.Repository
}

Esta estructura que llamamos UserRouter contiene el campo Repository, que es del tipo user.Repository, este tipo es una interfaz creada en la segunda parte, cuyos métodos coinciden con el tipo UserRepository que creamos en la tercera parte. Esta no es una casualidad, se realizo intencionalmente para poder usar UserRepository como user.Repository.

Es posible que se estén preguntando que caso tiene usar la interfaz en lugar de directamente utilizar UserRepository, en nuestro caso no habría mucha diferencia, pero utilizar la interfaz brinda varias ventajas, principalmente hace fácil remplazar el Repository por cualquier tipo que satisfaga la interfaz, por ejemplo otra implementación utilizando un motor de bases de datos diferente, o un tipo falso creado solo para propósitos de testing

Crear un usuario

Comencemos por el método de crear usuario, el objetivo es recibir un usuario en formato JSON desde el cuerpo de la petición deserializarlo en una variable de tipo user.User y almacenarlo en nuestra base de datos.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) CreateHandler(w http.ResponseWriter, r *http.Request) {
    var u user.User
    err := json.NewDecoder(r.Body).Decode(&u)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    defer r.Body.Close()

    ctx := r.Context()
    err = ur.Repository.Create(ctx, &u)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    u.Password = ""
    w.Header().Add("Location", fmt.Sprintf("%s%d", r.URL.String(), u.ID))
    response.JSON(w, r, http.StatusCreated, response.Map{"user": u})
}

En primer lugar estamos definiendo una variable u de tipo user.User, luego usamos la función NewDecoder del paquete json, de la librería estándar para obtener un puntero json.Decoder, que usamos inmediatamente para deserializar la data dentro de la variable u, es importante que sea un puntero porque necesita acceder a su lugar en memoria y realizar cambios en su valor.

Como pueden ver, estamos utilizando la función HTTPError del paquete response que creamos en un inicio para enviar una respuesta de error en caso de que exista, este proceso lo estaremos realizando frecuentemente en los handlers.

Creamos el usuario utilizando el método Create de Repository, al cual le pasamos un context.Context, en este caso el Context del Request, y un puntero a nuestra variable u que es ese punto contiene los datos del usuario a crear. Comprobamos si existe un error, de manera similar a lo hecho anteriormente.

Cambiamos el valor de la contraseña del usuario a un string vació para que el campo sea ignorado al generar el JSON. Agregamos a la cabecera de la respuesta el campo Location dando como valor la dirección del recurso que acabamos de crear, esto ultimo no es obligatorio pero es una buena practica. Para, finalmente, enviar una respuesta de JSON, gracias a la función JSON del paquete response que creamos al inicio (les dije que seria útil 😁) con el código de estado 201 (created).

Podrán notar que como data no estamos enviando directamente el usuario sino que este es enviado como valor de un campo llamado user en el response.Map, yo acostumbro enviarlo de esa forma pero si prefieren enviar el usuario directamente es valido.

Obtener usuarios

Ahora que ya podemos crear usuario veamos como obtener los usuarios ya registrados.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) GetAllHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    users, err := ur.Repository.GetAll(ctx)
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"users": users})
}

En este caso no necesitamos información proveniente del usuario, utilizamos el método GetAll de Repository para obtener todos los usuarios, comprobamos la existencia de un error y enviamos una respuesta de tipo JSON con los usuarios obtenidos, esta vez con el código 200 (OK).

Obtener un usuario

Con el método GetAllHandler podemos obtener todos los usuarios, pero algunas veces solo necesitamos la información de un usuario, así que vamos a crear un handler que nos permita hacer eso.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) GetOneHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    ctx := r.Context()
    u, err := ur.Repository.GetOne(ctx, uint(id))
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"user": u})
}

Para obtener un usuario especifico es necesaria una manera de identificarlo, en nuestro caso la mejor opción es el id asignado por la base de datos. Entonces necesitamos obtener ese id en a petición de alguna manera, considerando que sera una petición GET y no se debería enviar información por el Body. Una manera muy común de realizar esto es por medio de Query o como parámetros en la URL, vamos utilizar este ultimo, y chi nos facilita el trabajo gracias la función URLParam con la que podemos obtener el valor de un parámetro de la URL del http.Request.

Es importante resaltar que la función URLParam retorna un string, pero nosotros necesitamos el valor como un int (como un uint realmente pero esa es una conversión sencilla 😀), cosa que podemos realizar fácilmente con la función Atoi del paquete strconv.

El resto es muy similar a lo que hicimos en el handler GetAllHandler, solo que esta vez utilizamos el método GetOne de Repository y no olviden convertir el id a uint antes de pasarlo a la función. Si todo ha marchado bien, retornamos el usuario en formato JSON.

Actualizar usuario

Ahora que ya podemos crear usuarios y obtener un usuario ya creado, vamos como actualizar un usuario existente.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) UpdateHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    var u user.User
    err = json.NewDecoder(r.Body).Decode(&u)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    defer r.Body.Close()

    ctx := r.Context()
    err = ur.Repository.Update(ctx, uint(id), u)
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, nil)
}

Esta combina varias cosas que vimos anteriormente en GetOneHandler como obtener el id y convertirlo a int, con cosas que vimos en CreateHandler para deserializar JSON con ayuda del paquete json.

Hecho esto, utilizamos el método Update de Repository para actualizar el usuario y si no existe algún error enviamos una respuesta con estado 200 (OK), en este caso sin data. También se podría considerar retornar el usuario actualizado, pero mantengamos esto sencillo.

Borrar un usuarios

Podemos crear, actualizar y leer usuario, eso es genial, pero aun no falta una operación para completar nuestro CRUD, y esa es borrar.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) DeleteHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    ctx := r.Context()
    err = ur.Repository.Delete(ctx, uint(id))
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{})
}

Este handler es bastante sencillo y muy parecido a GetOneHandler. Solo obtenemos el id de la URL, lo convertimos a int y utilizamos el método Delete de Repository para eliminar el usuario con el correspondiente id. Finalmente enviando una respuesta JSON con código 200 (OK) y un objeto vacío para representar que se borro satisfactoriamente.

Definiendo rutas

Hasta ahora tenemos definida la lógica para manejar las peticiones pero aun no definimos que rutas deben ser manejadas por cada handler. Esto es bastante fácil con ayuda de chi y similares.

El donde y como definir las rutas puede variar, simplemente pueden ponerlo donde las parezca mas intuitivo, en este caso lo haremos de la siguiente manera:

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()
    // TODO: add routes.

    return r
}

En este nuevo método, que llamamos Routes, vamos a definir las rutas especificas para el modelo usuario. Aprovechemos para aprender un poco sobre la manera en la que manejamos las rutas con chi, comenzaremos con GetAllHandler de esta manera:

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.Get("/", ur.GetAllHandler)
    return r
}

Como pueden ver, r que es una puntero al tipo chi.Mux tiene métodos que hacen referencia a los métodos http como GET, POST, PUT, DELETE, entre otros. De esta manera es muy sencillo vincular un handler con un método http especifico.

Gracias a lo anterior, podemos vincular el método CreateHandler al mismo patrón de ruta pero con un método http diferente, en este caso POST.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.Get("/", ur.GetAllHandler)

    r.Post("/", ur.CreateHandler)

    return r
}

De igual forma podemos agregar el resto de los handlers, pero debemos recordar que los tres restantes tomaban un parámetro por su URL y aun no hemos visto como hacer eso. Así que tomemos como ejemplo el método GetOneHandler.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.Get("/", ur.GetAllHandler)

    r.Post("/", ur.CreateHandler)

    r.Get("/{id}", ur.GetOneHandler)

    return r
}

Como posiblemente supongan, con esas sintaxis de llaves ({}) podemos definir los parámetros en la URL, y el texto que se encuentra dentro de ellas sera el que usaremos como clave al momento de recuperar ese valor gracias a la función URLParam del paquete chi, que en este caso es id. Ahora que sabemos esto, es bastante sencillo agregar los handlers restantes con sus respectivos métodos: DELETE para DeleteHandler y PUT para UpdateHandler.

// internal/server/v1/user_router.go
// […]

func (ur *UserRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.Get("/", ur.GetAllHandler)

    r.Post("/", ur.CreateHandler)

    r.Get("/{id}", ur.GetOneHandler)

    r.Put("/{id}", ur.UpdateHandler)

    r.Delete("/{id}", ur.DeleteHandler)

    return r
}

Rutas de publicaciones

Este proceso un bastante similar al que realizamos con los usuarios, así que avanzaremos mas rápido o resultaría muy repetitivo. Voy a compartir el código en cada caso y solo me detendré a explicar puntos que, a mi criterio, requieran mayor explicación.

Si algo no les queda claro, siéntanse libres de dirigirse (con o sin antorchas 😬) hacia la caja de comentarios y les responderé tan pronto como me resulte posible.

Iniciamos creando un nuevo archivo dentro de paquete v1 al cual llamaremos post_router.go

touch internal/server/v1/post_router.go

Y agregamos el siguiente contenido.

// internal/server/v1/post_router.go
package v1

import (
    "github.com/orlmonteverde/go-postgres-microblog/pkg/post"
)

type PostRouter struct {
    Repository post.Repository
}

Hecho esto, podemos comenzar a agregar los métodos correspondientes.

Crear publicación

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) CreateHandler(w http.ResponseWriter, r *http.Request) {
    var p post.Post
    err := json.NewDecoder(r.Body).Decode(&p)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    defer r.Body.Close()

    ctx := r.Context()
    err = pr.Repository.Create(ctx, &p)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    w.Header().Add("Location", fmt.Sprintf("%s%d", r.URL.String(), p.ID))
    response.JSON(w, r, http.StatusCreated, response.Map{"post": p})
}

Obtener publicaciones

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) GetAllHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    posts, err := pr.Repository.GetAll(ctx)
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"posts": posts})
}

Obtener una publicación

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) GetOneHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    ctx := r.Context()
    p, err := pr.Repository.GetOne(ctx, uint(id))
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"post": p})
}

Actualizar publicación

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) UpdateHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    var p post.Post
    err = json.NewDecoder(r.Body).Decode(&p)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    defer r.Body.Close()

    ctx := r.Context()
    err = pr.Repository.Update(ctx, uint(id), p)
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, nil)
}

Borrar publicación

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) DeleteHandler(w http.ResponseWriter, r *http.Request) {
    idStr := chi.URLParam(r, "id")

    id, err := strconv.Atoi(idStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    ctx := r.Context()
    err = pr.Repository.Delete(ctx, uint(id))
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{})
}

Obtener las publicaciones de un usuario

¿Recuerdan que comente antes que solo me detendría a explicar detalles que considerara diferentes a los ya explicados para UserRouter? Pues para que no parezca que solo estoy pegando código (eso estaba haciendo 🤫), explicare este handler un poco, aunque es bastante parecido a GetOneHandler.

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) GetByUserHandler(w http.ResponseWriter, r *http.Request) {
    userIDStr := chi.URLParam(r, "userId")

    userID, err := strconv.Atoi(userIDStr)
    if err != nil {
        response.HTTPError(w, r, http.StatusBadRequest, err.Error())
        return
    }

    ctx := r.Context()
    posts, err := pr.Repository.GetByUser(ctx, uint(userID))
    if err != nil {
        response.HTTPError(w, r, http.StatusNotFound, err.Error())
        return
    }

    response.JSON(w, r, http.StatusOK, response.Map{"posts": posts})
}

En este caso el parámetro que estamos extrayendo de la URL no se llama id sino userId, aunque esto es un detalle menor, podríamos llamarlo de la manera en la que consideremos mas adecuada siempre y cuando usemos la misma clave al definir la ruta. Realizamos la conversión de string a int, utilizamos el método GetByUser de Repository para obtener las publicaciones relacionadas a un usuario por su id y enviamos la respuesta de tipo JSON.

Definiendo rutas

De manera similar al lo que realizamos con UserRouter, crearemos un método Routes que retorne un http.Handler dentro del cual definiremos nuestras rutas.

// internal/server/v1/post_router.go
// […]

func (pr *PostRouter) Routes() http.Handler {
    r := chi.NewRouter()

    r.Get("/user/{userId}", pr.GetByUserHandler)

    r.Get("/", pr.GetAllHandler)

    r.Post("/", pr.CreateHandler)

    r.Get("/{id}", pr.GetOneHandler)

    r.Put("/{id}", pr.UpdateHandler)

    r.Delete("/{id}", pr.DeleteHandler)

    return r
}

Conectando las rutas

Actualmente tenemos nuestras funciones handler y rutas definidas tanto para usuarios como para publicaciones, pero aunque levantemos el servidor no podremos realizar consultas a estas rutas porque aun no las conectamos a nuestro Server. Así que crearemos un nuevo archivo dentro del paquete v1 al que llamaremos api.go.

touch internal/server/v1/api.go

Y agregamos el siguiente contenido

// internal/server/v1/api.go
package v1

import (
    "net/http"

    "github.com/go-chi/chi"
)

func New() http.Handler {
    r := chi.NewRouter()

    return r
}

En este punto vamos a aprovechar la posibilidad de agrupar rutas que nos proporciona chi, pero primero debemos definir una nueva variable de tipo puntero a UserRouter.

// internal/server/v1/api.go
// […]

func New() http.Handler {
    r := chi.NewRouter()

    ur := &UserRouter{
        Repository: &data.UserRepository{
            Data: data.New(),
        },
    }

    return r
}

Nuestra nueva variable ur es un puntero a UserRouter en el que estamos inicializando su campo Repository con un puntero al tipo data.UserRepository que desarrollamos en la parte 3, el cual, a su vez, contiene un campo llamado Data que es un puntero al tipo data.Data y lo estamos inicializando gracias a la función New del paquete data que creamos en la parte 2.

// internal/server/v1/api.go
// […]

func New() http.Handler {
    r := chi.NewRouter()

    ur := &UserRouter{Repository:
        &data.UserRepository{Data: data.New()},
    }

    r.Mount("/users", ur.Routes())

    return r
}

Con nuestra variable ur preparada podemos utilizar la el método Mount del Router podemos anidar las rutas definidas dentro del http.Handler que retorna el método Routes de nuestro UserRouter. Dicho de otra forma, las rutas que definimos dentro de Routes ahora tendrán como base /users, por ejemplo, para el caso de r.Get("/", ur.GetAllHandler), la ruta sera /users/. Quedara mas claro en un momento cuando realicemos peticiones de prueba a nuestra API.

// internal/server/v1/api.go
// […]

func New() http.Handler {
    r := chi.NewRouter()

    // [...]

    pr := &PostRouter{
        Repository: &data.PostRepository{
            Data: data.New(),
        },
    }

    r.Mount("/posts", pr.Routes())

    return r
}

De manera similar agregamos nuestras rutas para publicaciones, en este caso bajo la ruta /posts. Hecho esto, vamos a nuestro archivo server.go en el paquete server (internal/server/server.go) y agregamos las rutas de nuestra API versión uno.

// internal/server/server.go
package server

// [...]

// New inicialize a new server with configuration.
func New(port string) (*Server, error) {
    r := chi.NewRouter()

    // API routes version 1.
    r.Mount("/api/v1", v1.New())

    serv := &http.Server{
        Addr:         ":" + port,
        Handler:      r,
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 10 * time.Second,
    }

    server := Server{server: serv}

    return &server, nil
}

// [...]

Ahora ya tenemos nuestras rutas correctamente configuradas 😀. Vamos levantar el servidor y hacer pruebas.

go build ./cmd/microblog && ./microblog

Si ahora visitamos desde nuestro navegador de confianza la dirección http://localhost:9000/api/v1/users/ deberían obtener una salida similar a la siguiente.

{"users":null}

De igual forma si visitamos http://localhost:9000/api/v1/posts/.

{"posts":null}

Tenia la intención de realizar las pruebas a todos los endpoints con curl y/o postman, pero esta parte se ha extendido bastante, así que lo estaremos abordando en la siguiente junto con JSON Web Tokens.

Por ahora lo dejaremos hasta aquí, en el siguiente articulo continuaremos con el desarrollo de nuestra API. Les comparto el repositorio con el código del proyecto hasta el momento.

API Rest con Go (Golang) y PostgreSQL Parte 3

Orlando Monteverde — Wed, 20 May 2020 08:06:30 +0000

Requisitos:

Conocimientos básicos sobre el lenguaje go.
Conocimiento sobre HTTP y REST recomendable.
Go en su versión 1.11 o superior.
PostgreSQL en su versión 9.6 o superior.
Conocimientos básicos de SQL deseables.
Ganas de aprender.

Que vamos a desarrollar

Indice

Esta es la tercera parte, recomiendo comenzar por el primer articulo. O si gustas revisa el articulo anterior. De cualquier forma, el código del que vamos a partir en este artículo se encuentra en este repositorio.

Repositorios

Ahora vamos a crear script de SQL para crear las tablas correspondientes a nuestros modelos: user y post. No me detendré a explicar detalladamente el código porque no es el propósito de esta publicación, si gustas puedes darte una vuelta por este tutorial.

Si ya conoces SQL seguro sera fácil de entender y en caso contrario simplemente estamos creando una tabla llamada users, con columnas que corresponden a los campos de nuestra estructura user. De igual forma, una tabla posts, que corresponde a nuestra estructura post, que se relaciona con los usuarios por medio del campo user_id, que corresponde a un id de usuario.

CREATE TABLE IF NOT EXISTS users (
    id serial NOT NULL,
    first_name VARCHAR(150) NOT NULL,
    last_name VARCHAR(150) NOT NULL,
    username VARCHAR(150) NOT NULL UNIQUE,
    password varchar(256) NOT NULL,
    email VARCHAR(150) NOT NULL UNIQUE,
    picture VARCHAR(256) NOT NULL,
    created_at timestamp DEFAULT now(),
    updated_at timestamp NOT NULL,
    CONSTRAINT pk_users PRIMARY KEY(id)
);

CREATE TABLE IF NOT EXISTS posts (
    id serial NOT NULL,
    user_id int NOT NULL,
    body text NOT NULL,
    created_at timestamp DEFAULT now(),
    updated_at timestamp NOT NULL,
    CONSTRAINT pk_notes PRIMARY KEY(id),
    CONSTRAINT fk_posts_users FOREIGN KEY(user_id) REFERENCES users(id)
);

Seria posible utilizar este código en nuestro motor de base de datos bien sea copiando y pegando o ejecutándolo directamente, pero vamos colocarlo dentro de un directorio llamado database en la raíz de nuestro proyecto y a darle el nombre de models.sql por un lado para que tengan acceso al archivo y por otro para que nuestra aplicación pueda leerlo y encargarse de ejecutarlo.

Regresamos al archivo postgres.sql y realizamos algunos cambios. Importamos el paquete ioutil de la biblioteca estándar, que nos permitirá leer el archivo y agregamos una nueva función a la que llamamos MakeMigration, que se encargara de leer nuestro archivo models.sql y de ejecutar las instrucciones que escribimos en el.

// internal/data/postgres.go
// […]

func MakeMigration(db *sql.DB) error {
    b, err := ioutil.ReadFile("./database/models.sql")
    if err != nil {
        return err
    }

    rows, err := db.Query(string(b))
    if err != nil {
        return err
    }

    return rows.Close()
}

Ahora debemos ejecutar esta función, vamos a hacerlo en la funcion initDB que creamos antes, en el archivo data.go

// internal/data/data.go
// […]
func initDB() {
    db, err := getConnection()
    if err != nil {
        log.Panic(err)
    }

    err = MakeMigration(db)
    if err != nil {
        log.Panic(err)
    }

    data = &Data{
        DB: db,
    }
}
[…]

Hecho esto, vamos a compilar y ejecutar nuevamente nuestro programa para comprobar que, hasta este punto, todo este funcionando como esperamos.

go build ./cmd/microblog && ./microblog

Si no tenemos errores, el programa debería compilar, ejecutarse y mostrar el mensaje de que el servidor esta corriendo, similar al siguiente.

2020/05/19 17:28:21 Server running on http://localhost:9000

Y si revisamos la base de datos, deberíamos tener las tablas correctamente creadas.

 Schema |     Name     |   Type   | Owner  
--------+--------------+----------+--------
 public | posts        | table    | gopher
 public | posts_id_seq | sequence | gopher
 public | users        | table    | gopher
 public | users_id_seq | sequence | gopher

Usuarios

Ahora que tenemos nuestras tablas creadas procederemos con las operaciones CRUD para nuestro usuario. Dentro del paquete data crearemos una estructura llamada UserRepository a la que agregaremos los métodos necesarios para satisfacer la interfaz Repository que creamos anteriormente dentro del paquete user.

Esta nueva estructura podemos colocarla donde nos parezca mas conveniente, mientras se encuentre dentro del paquete data. Vamos a crearla en un nuevo archivo llamado user_repository.go porque, en mi opinión, es mas cómodo y organizado.

// internal/data/user_repository.go
package data

type UserRepository struct {
    Data *Data
}

Obtener todos

Comencemos por el método GetAll, que nos permitirá obtener todos los usuarios en la tabla users.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) GetAll(ctx context.Context) ([]user.User, error) {
    q := `
    SELECT id, first_name, last_name, username, email, picture,
        created_at, updated_at
        FROM users;
    `

    rows, err := ur.Data.DB.QueryContext(ctx, q)
    if err != nil {
        return nil, err
    }

    defer rows.Close()

    var users []user.User
    for rows.Next() {
        var u user.User
        rows.Scan(&u.ID, &u.FirstName, &u.LastName, &u.Username,
            &u.Email, &u.Picture, &u.CreatedAt, &u.UpdatedAt)
        users = append(users, u)
    }

    return users, nil
}

En primer lugar, definimos la consulta dentro de la variable que llamamos q, la ejecutamos por medio del método QueryContext, lo que nos retorna un valor de tipo puntero sql.Rows, el cual nos aseguramos de cerrar con su metodo Close gracias a defer. Entonces definimos una variable users que sera donde almacenaremos los usuarios y utilizamos un ciclo for en conjunto con el método Next, que retorna un Bool que sera true mientras existan filas por leer.

Dentro de este ciclo definimos una variable llama u de tipo user.User donde almacenaremos la información de cada usuario leído mediante el método Scan del tipo sql.Rows para posteriormente agregarlo a users. Finalmente, retornamos la colección de usuarios y y el valor nil para indicar que el proceso concluyo satisfactoriamente.

Obtener uno

Este método es muy similar al caso anterior, solo que retornamos un único usuario.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) GetOne(ctx context.Context, id uint) (user.User, error) {
    q := `
    SELECT id, first_name, last_name, username, email, picture,
        created_at, updated_at
        FROM users WHERE id = $1;
    `

    row := ur.Data.DB.QueryRowContext(ctx, q, id)

    var u user.User
    err := row.Scan(&u.ID, &u.FirstName, &u.LastName, &u.Username, &u.Email,
        &u.Picture, &u.CreatedAt, &u.UpdatedAt)
    if err != nil {
        return user.User{}, err
    }

    return u, nil
}

No hay mucho que destacar en este fragmento de código, es bastante similar al anterior, con excepción de que, en este caso, vamos a pasar argumentos a la consulta, cosa que indicamos con la sintaxi ${numero correspondiente al orden en el que se pasa el argumento}, esto varia según el motor de base de datos que se este utilizando, en este caso es valido para PostgreSQL, pero en el caso de, por ejemplo, MySQL o SQLite se utiliza ? en su lugar.

Otro detalle a destacar es el uso del método QueryRowContext en lugar de QueryContext que utilizamos anteriormente, esto se debe a que esta consulta solo retornara una fila. Ademas, esta vez estamos pasando como tercer argumento el id del usuario, que tomara el lugar del $1 que definimos dentro del string que almacenamos en q.

Obtener por username

De manera casi idéntica al caso anterior, vamos a retornar un único usuario, solo que esta vez mediante su username en lugar de su id.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) GetByUsername(ctx context.Context, username string) (user.User, error) {
    q := `
    SELECT id, first_name, last_name, username, email, picture,
        password, created_at, updated_at
        FROM users WHERE username = $1;
    `

    row := ur.Data.DB.QueryRowContext(ctx, q, username)

    var u user.User
    err := row.Scan(&u.ID, &u.FirstName, &u.LastName, &u.Username,
        &u.Email, &u.Picture, &u.PasswordHash, &u.CreatedAt, &u.UpdatedAt)
    if err != nil {
        return user.User{}, err
    }

    return u, nil
}

¿Pueden encontrar las diferencias con el método GetOne? 😁. Sino, no se preocupen, son realmente parecidas, la diferencia mas destacable seria el uso del username en lugar del id, otro, quizás menos visible, es que ahora estamos solicitando la columna password en la consulta y, a su vez, ese valor lo estamos almacenando en el campo PasswordHash del usuario.

La razón por la que estamos solicitando el la contraseña esta vez es porque el método GetByUsername sera utilizado mas adelante para manejar el ingreso de usuarios y sera necesario comparar la contraseña con la que tenemos almacenada en la base de datos.

Insertar

Ahora es momento de agregar nuevos usuarios a la tabla, para ese fin preparamos la consulta correspondiente, esta vez utilizando insert into.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) Create(ctx context.Context, u *user.User) error {
    q := `
    INSERT INTO users (first_name, last_name, username, email, picture, password, created_at, updated_at)
        VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
        RETURNING id;
    `

    if u.Picture == "" {
        u.Picture = "https://placekitten.com/g/300/300"
    }

    if err := u.HashPassword(); err != nil {
        return err
    }

    row := ur.Data.DB.QueryRowContext(
        ctx, q, u.FirstName, u.LastName, u.Username, u.Email,
        u.Picture, u.PasswordHash, time.Now(), time.Now(),
    )

    err := row.Scan(&u.ID)
    if err != nil {
        return err
    }

    return nil
}

Realizamos una pequeña validación para agregar una imagen por defecto si el usuario no incluye una, en este caso un simpático gato desde placekitten. Generamos el PasswordHash gracias al método HashPassword que creamos en el primer articulo y ejecutamos la sentencia para, finalmente, leer el valor del id que le fue asignado al nuevo usuario ya que lo usaremos mas adelante.

Actualizar

Ahora que podemos obtener y crear usuarios vamos a agregar un método que nos permita actualizar un usuario existente.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) Update(ctx context.Context, id uint, u user.User) error {
    q := `
    UPDATE users set first_name=$1, last_name=$2, email=$3, picture=$4, updated_at=$5
        WHERE id=$6;
    `

    stmt, err := ur.Data.DB.PrepareContext(ctx, q)
    if err != nil {
        return err
    }

    defer stmt.Close()

    _, err = stmt.ExecContext(
        ctx, u.FirstName, u.LastName, u.Email,
        u.Picture, time.Now(), id,
    )
    if err != nil {
        return err
    }

    return nil
}

Para actualizar utilizamos la sentencia SQL update y, de esta forma, actualizamos todos los campos del usuarios (con excepción de id, username, password y created_at) que corresponda con el id dado.

Borrar

Ahora es momento de borrar un usuario, la operación restante para completar nuestro CRUD.

// internal/data/user_repository.go
// […]
func (ur *UserRepository) Delete(ctx context.Context, id uint) error {
    q := `DELETE FROM users WHERE id=$1;`

    stmt, err := ur.Data.DB.PrepareContext(ctx, q)
    if err != nil {
        return err
    }

    defer stmt.Close()

    _, err = stmt.ExecContext(ctx, id)
    if err != nil {
        return err
    }

    return nil
}

Este método es uno de los mas sencillos, simplemente usamos la sentencia SQL delete para eliminar al usuario cuyo id corresponda con el dado. La clausula where es muy importante para esto ultimo, de otra forma eliminaríamos todos los usuarios en la tabla y probablemente no es lo que buscamos 😜.

Publicaciones

Ahora es momento del CRUD para las publicaciones. De manera similar al como lo hicimos para user crearemos un archivo llamado post_repository.go dentro del paquete data y lo primero que haremos sera agregar una estructura que llamaremos PostRepository.

// internal/data/post_repository.go
package data

type PostRepository struct {
    Data *Data
}

Para esta estructura, como podrán suponer por el caso anterior, agregaremos los métodos correspondientes para satisfacer la interfaz Repository en el paquete post que definimos en el primer articulo.

Debido a que todo el proceso es prácticamente igual al que realizamos para el caso de los usuarios solo me detendré a explicar el método para obtener todos las publicaciones de un usuario que considero ligeramente diferente a los ya vistos y para los demás casos voy a compartir el código ¿todos a favor?

Obtener todos

// internal/data/post_repository.go
// […]
func (pr *PostRepository) GetAll(ctx context.Context) ([]post.Post, error) {
    q := `
    SELECT id, body, user_id, created_at, updated_at
        FROM posts;
    `

    rows, err := pr.Data.DB.QueryContext(ctx, q)
    if err != nil {
        return nil, err
    }

    defer rows.Close()

    var posts []post.Post
    for rows.Next() {
        var p post.Post
        rows.Scan(&p.ID, &p.Body, &p.UserID, &p.CreatedAt, &p.UpdatedAt)
        posts = append(posts, p)
    }

    return posts, nil
}

Obtener uno

// internal/data/post_repository.go
// […]
func (pr *PostRepository) GetOne(ctx context.Context, id uint) (post.Post, error) {
    q := `
    SELECT id, body, user_id, created_at, updated_at
        FROM posts WHERE id = $1;
    `

    row := pr.Data.DB.QueryRowContext(ctx, q, id)

    var p post.Post
    err := row.Scan(&p.ID, &p.Body, &p.UserID, &p.CreatedAt, &p.UpdatedAt)
    if err != nil {
        return post.Post{}, err
    }

    return p, nil
}

Obtener todas las publicaciones de un usuario

Este método es bastante parecido al de GetAll, con la diferencia de que no obtendremos todas las publicaciones en la tabla sino que las filtraremos por el id de un usuario, agregando la clausula SQL where al final de la consulta.

// internal/data/post_repository.go
// […]
func (pr *PostRepository) GetByUser(ctx context.Context, userID uint) ([]post.Post, error) {
    q := `
    SELECT id, body, user_id, created_at, updated_at
        FROM posts
        WHERE user_id = $1;
    `

    rows, err := pr.Data.DB.QueryContext(ctx, q, userID)
    if err != nil {
        return nil, err
    }

    defer rows.Close()

    var posts []post.Post
    for rows.Next() {
        var p post.Post
        rows.Scan(&p.ID, &p.Body, &p.UserID, &p.CreatedAt, &p.UpdatedAt)
        posts = append(posts, p)
    }

    return posts, nil
}

Insertar

// internal/data/post_repository.go
// […]
func (pr *PostRepository) Create(ctx context.Context, p *post.Post) error {
    q := `
    INSERT INTO posts (body, user_id, created_at, updated_at)
        VALUES ($1, $2, $3, $4)
        RETURNING id;
    `

    stmt, err := pr.Data.DB.PrepareContext(ctx, q)
    if err != nil {
        return err
    }

    defer stmt.Close()

    row := stmt.QueryRowContext(ctx, p.Body, p.UserID, time.Now(), time.Now())

    err = row.Scan(&p.ID)
    if err != nil {
        return err
    }

    return nil
}

Actualizar

// internal/data/post_repository.go
// […]
func (pr *PostRepository) Update(ctx context.Context, id uint, p post.Post) error {
    q := `
    UPDATE posts set body=$1, updated_at=$2
        WHERE id=$3;
    `

    stmt, err := pr.Data.DB.PrepareContext(ctx, q)
    if err != nil {
        return err
    }

    defer stmt.Close()

    _, err = stmt.ExecContext(
        ctx, p.Body, time.Now(), id,
    )
    if err != nil {
        return err
    }

    return nil
}

Borrar

// internal/data/post_repository.go
// […]
func (pr *PostRepository) Delete(ctx context.Context, id uint) error {
    q := `DELETE FROM posts WHERE id=$1;`

    stmt, err := pr.Data.DB.PrepareContext(ctx, q)
    if err != nil {
        return err
    }

    defer stmt.Close()

    _, err = stmt.ExecContext(ctx, id)
    if err != nil {
        return err
    }

    return nil
}

Por ahora lo dejaremos hasta aquí, en el siguiente articulo continuaremos con el desarrollo de nuestra API. Les comparto el repositorio con el código del proyecto hasta el momento.

API Rest con Go (Golang) y PostgreSQL Parte 2

Orlando Monteverde — Wed, 13 May 2020 06:15:00 +0000

Requisitos:

Conocimientos básicos sobre el lenguaje go.
Conocimiento sobre HTTP y REST recomendable.
Go en su versión 1.11 o superior.
PostgreSQL en su versión 9.6 o superior.
Conocimientos básicos de SQL deseables.
Ganas de aprender.

Que vamos a desarrollar

Indice

Esta es la segunda parte, te recomiendo comenzar por el articulo anterior.

Creando los modelos

User

Primero crearemos un directorio llamado user dentro del directorio pkg y, dentro de este nuevo directorio, crearemos un archivo llamado user.go.

mkdir pkg/user && touch pkg/user/user.go

Vamos a crear la estructura User dentro de este archivo, que va a representar a los usuarios de nuestra API.

// pkg/user/user.go
package user

import "time"

// User of the system.
type User struct {
    ID           uint      `json:"id,omitempty"`
    FirstName    string    `json:"first_name,omitempty"`
    LastName     string    `json:"last_name,omitempty"`
    Username     string    `json:"username,omitempty"`
    Email        string    `json:"email,omitempty"`
    Picture      string    `json:"picture,omitempty"`
    Password     string    `json:"password,omitempty"`
    PasswordHash string    `json:"-"`
    CreatedAt    time.Time `json:"created_at,omitempty"`
    UpdatedAt    time.Time `json:"updated_at,omitempty"`
}

Esta estructura contendrá la información de nuestro usuario, bastante sencillo, un identificador único para gestionarlo dentro de la base de datos, información personal, como nombre, apellido y correo electrónico, el Username, que utilizaremos para el login y la contraseña, el campo PasswordHash sera utilizado para almacenar el hash de la contraseña generado por bcrypt, cosa que haremos en el siguiente paso. También tenemos los campos CreatedAt y UpdatedAt de tipo ** time.Time** que utilizaremos para mantener un registro de la fecha de cuando fue creado el usuario y cuando fue su ultima modificación.

Si te resultan extrañas las anotaciones junto a los campos en la estructura, simplemente son una menera conveniente de proporcionar información adicional que, en este caso, usa el paquete encoding/json para procesar los campos, como nombrarlos en minúscula y usando notación snake case, que omita el campo si esta vació (omitempty), o evitar exponer un campo al convertir la estructura a formato JSON (json:"-"). Para mas información, les recomiendo consultar este articulo.

Ahora, agregaremos dos métodos a la estructura User para gestionar las contraseñas. Pero, primero debemos descargar el paquete bcrypt.

go get golang.org/x/crypto/bcrypt

En primer lugar, una función para generar el hash a partir de la contraseña del usuario, para no almacenar esta directamente dentro de la base de datos. Esto se consigue facilmente gracias a la función GenerateFromPassword del paquete bcrypt que acabamos de instalar.

func (u *User) HashPassword() error {
    passwordHash, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
    if err != nil {
        return err
    }

    u.PasswordHash = string(passwordHash)

    return nil
}

De manera similar, crearemos un método que nos permita comparar el hash de la contraseña, almacenada en la propiedad PasswordHash, con la contraseña que recibe el método haciendo uso de la función CompareHashAndPassword del paquete bcrypt.

func (u User) PasswordMatch(password string) bool {
    err := bcrypt.CompareHashAndPassword([]byte(u.PasswordHash), []byte(password))

    return err == nil
}

Con esto ya hemos terminado con la estructura User. Ahora, dentro del mismo paquete user crearemos una interface que definirá las operaciones a realizar con el usuario en la base de datos. Esto puede realizarse en el mismo archivo user.go o en uno separado mientras comparta el mismo paquete, en este caso lo crearemos en un archivo diferente, ya que lo considero mas ordenado de esa forma, pero es solo una preferencia personal.

// pkg/user/repository.go
package user

import "context"

// Repository handle the CRUD operations with Users.
type Repository interface {
    GetAll(ctx context.Context) ([]User, error)
    GetOne(ctx context.Context, id uint) (User, error)
    GetByUsername(ctx context.Context, username string) (User, error)
    Create(ctx context.Context, user *User) error
    Update(ctx context.Context, id uint, user User) error
    Delete(ctx context.Context, id uint) error
}

Esto quizás no parezca tener demasiado sentido en este punto, pero facilita mucho operaciones como testing, ademas de que nos permite separar la lógica de los handlers de la base de datos, por que podrías usar alguna otra, incluso si es NoSQL como MongoDB sin cambios importantes. Pronto estaré compartiendo contenido sobre Go y MongoDB 😉.

Si no están familiarizados con el paquete context les recomiendo leer esta interesante publicación del blog de go. De cualquier forma, este paquete nos da acceso al tipo de dato Context que nos permite definir tiempos limite, cancelar grupos de operaciones, pasar valores a través del contexto, entre otras cosas.

Post

Ahora crearemos un directorio llamado post dentro del directorio pkg. Y, dentro de este nuevo directorio crearemos un archivo llamado post.go.

mkdir pkg/post && touch pkg/post/post.go

Y crearemos la estructura Post dentro de este archivo, que va a representar a las publicaciones de un usuario de nuestra API.

// pkg/post/post.go
package post

import "time"

// Post created by a user.
type Post struct {
    ID        uint      `json:"id,omitempty"`
    Body      string    `json:"body,omitempty"`
    UserID    uint      `json:"user_id,omitempty"`
    CreatedAt time.Time `json:"created_at,omitempty"`
    UpdatedAt time.Time `json:"updated_at,omitempty"`
}

Bastante similar al caso anterior. Ahora crearemos también una interface Repository para esta estructura.

// pkg/post/repository.go
package post

import "context"

// Repository handle the CRUD operations with Posts.
type Repository interface {
    GetAll(ctx context.Context) ([]Post, error)
    GetOne(ctx context.Context, id uint) (Post, error)
    GetByUser(ctx context.Context, userID uint) ([]Post, error)
    Create(ctx context.Context, post *Post) error
    Update(ctx context.Context, id uint, post Post) error
    Delete(ctx context.Context, id uint) error
}

Con esto ya tenemos suficiente para pasar a la siguiente fase, la base de datos.

Conexión con la base de datos.

Lo primero que debemos hacer es conectarnos a Postgres, pueden usar un cliente de terminal como psql que viene con la instalación de postgres, alguna interfaz gráfica como pgAdmin, lo que les resulte mejor, para el ejemplo usaremos psql.

psql -U postgres

En mi caso tengo el usuario de postgres sin contraseña, porque es una instalación local que uso para pruebas. Pero es posible que les solicite contraseña para ingresar si establecieron una.

Ahora debemos estar viendo un prompt parecido a este

postgres=#

En espera de comandos. Lo primero que haremos sera crear un nuevo usuario, esto no es obligatorio, perfectamente podríamos trabajar con el usuario postgres pero es mejor idea tener un usuario que solo tenga acceso a la base de datos del proyecto por seguridad.

postgres=# CREATE ROLE gopher WITH LOGIN PASSWORD 'gopher';

En el comando de arriba estamos creando un nuevo usuario llamado gopher, le estamos dando permiso para hacer login y le asignamos la super segura contraseña gopher. Esto solo para efectos del ejemplo, recomiendo usar una contraseña un poco mas segura 😁.

Al presionar la tecla ENTER el comando se ejecutara y deberíamos tener una respuesta indicando: CREATE ROLE.

Buen trabajado, ahora crearemos la base de datos que vamos a utilizar en nuestra API.

postgres=# CREATE DATABASE microblog OWNER gopher;

Si todo ha salido bien, tendríamos una respuesta similar a esta: CREATE DATABASE. Si desean confirmar que su base de datos fue creada exitosamente, puede listar las bases de datos con el comando \l y deberían obtener una respuesta como la siguiente.

 microblog         | gopher   | UTF8     | en_US.utf8 | en_US.utf8 | 
 postgres          | postgres | UTF8     | en_US.utf8 | en_US.utf8 | 
 template0         | postgres | UTF8     | en_US.utf8 | en_US.utf8 | =c/postgres          +
                   |          |          |            |            | postgres=CTc/postgres
 template1         | postgres | UTF8     | en_US.utf8 | en_US.utf8 | =c/postgres          +
                   |          |          |            |            | postgres=CTc/postgres

De momento hemos terminado y podemos desconectarnos de Postgres. Desde psql podemos hacerlo por medio del comando \q.

De regreso a nuestro proyecto, crearemos un nuevo directorio llamado data, dentro del directorio internal, este nuevo directorio debería quedar al mismo nivel que server.

mkdir internal/data && touch internal/data/data.go

Y dentro de este nuevo directorio crearemos un archivo llamado data.go, que inicialmente contendrá el siguiente código.

package data

import (
    "database/sql"
    "sync"
)

var (
    data *Data
    once sync.Once
)

// Data manages the connection to the database.
type Data struct {
    DB *sql.DB
}

Hecho eso, crearemos un nuevo archivo dentro del mismo paquete al que llamaremos postgres.go, aquí definiremos la conexión con la base de datos que creamos anteriormente. Antes de avanzar, vamos a descargar un nuevo paquete, en este caso un driver para postgres llamado pq

go get github.com/lib/pq

Ahora vamos a agregar algo de código a nuestro archivo postgres.go.

// internal/data/postgres.go
package data

import (
    "database/sql"

    // registering database driver
    _ "github.com/lib/pq"
)

func getConnection() (*sql.DB, error) {
    uri := "postgres://gopher:gopher@127.0.0.1:5432/microblog?sslmode=disable"
    return sql.Open("postgres", uri)
}

El string que tenemos dentro de la variable uri nos permite conectarnos a la base de datos que creamos anteriormente. Indicando el nombre de usuario, su contraseña, la IP y puerto en el que esta corriendo postgres y el nombre de la base de datos a la que queremos conectarnos.

Sin embargo, similar al caso que del puerto, que tratamos en la publicación anterior, no es conveniente tener esta información directamente dentro del código, así que haremos un par de cambios para obtenera como variable de entorno.

Agregamos una nueva variable a nuestro archivo .env.

# .env
PORT=9000
DATABASE_URI=postgres://gopher:gopher@127.0.0.1:5432/microblog?sslmode=disable

Y modificamos el archivo postgres.go para leer el valor de esta variable de entorno.

package data

import (
    "database/sql"
    "os"

    // registering database driver
    _ "github.com/lib/pq"
)

func getConnection() (*sql.DB, error) {
    uri := os.Getenv("DATABASE_URI")
    return sql.Open("postgres", uri)
}

Ahora regresamos al archivo data.go para hacer algunos cambios. Primero, agregamos una función llamada initDB que creara una nueva conexión al base de datos gracias a la función getConnection que creamos anteriormente e inicializara el la variable data con un nuevo puntero a Data que contiene la conexión que acabamos de crear.

// internal/data/data.go
func initDB() {
    db, err := getConnection()
    if err != nil {
        log.Panic(err)
    }

    data = &Data{
        DB: db,
    }
}

Una función llamada New con la que obtendremos un puntero a Data, para evitar crear una nueva conexión a la base de datos cada vez que llamamos a la función New utilizamos el tipo once del paquete sync que forma parte de la biblioteca estándar.

func New() *Data {
    once.Do(initDB)

    return data
}

Y agregaremos una función llamada Close que usaremos para cerrar los recurso que hayamos abierto, en este caso, la conexión a la base de datos.

Ahora, para comprobar si la conexión se esta realizando correctamente, regresaremos al archivo main.go (cmd/microblog/main.go), y agregamos la llamada a la función New previamente creada y utilizamos la conexión para realizar un Ping a la base de datos y, finalmente, usamos la función Close para cerrar los recursos una vez que interrumpimos la ejecución del programa.

// cmd/microblog/main.go
package main

import (
    "os"
    "os/signal"

    "log"

    "github.com/orlmonteverde/go-postgres-microblog/internal/data"
    "github.com/orlmonteverde/go-postgres-microblog/internal/server"

    _ "github.com/joho/godotenv/autoload"
)

func main() {
    port := os.Getenv("PORT")
    serv, err := server.New(port)
    if err != nil {
        log.Fatal(err)
    }

    // connection to the database.
    d := data.New()
    if err := d.DB.Ping(); err != nil {
        log.Fatal(err)
    }

    // start the server.
    go serv.Start()

    // Wait for an in interrupt.
    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt)
    <-c

    // Attempt a graceful shutdown.
    serv.Close()
    data.Close()
}

Por ahora lo dejaremos hasta aquí, en el siguiente articulo continuaremos con el desarrollo de nuestra API. Les comparto el repositorio con el código del proyecto hasta el momento.

API Rest con Go (Golang) y PostgreSQL Parte 1

Orlando Monteverde — Tue, 14 Apr 2020 00:05:28 +0000

Desarrollo de una API Rest sencilla con Go y el motor de base de datos PostgreSQL.

Requisitos:

Conocimientos básicos sobre el lenguaje go.
Conocimiento sobre HTTP y REST recomendable.
Go en su versión 1.11 o superior.
PostgreSQL en su versión 9.6 o superior.
Conocimientos básicos de SQL deseables.
Ganas de aprender.

Que vamos a desarrollar

Indice

Crearemos una carpeta para nuestro proyecto

Pueden darle el nombre de su preferencia a la carpeta y colocarla donde les parezca adecuado, en mi caso la llamare go-postgres-microblog para identificarla con facilidad. También puede crearla desde su gestor de archivos, a mi me gusta usar la terminal y sentirme hacker.

mkdir go-postgres-microblog && cd $_

Iniciando un modulo de go

Una vez dentro de la carpeta deseada, desde el terminal escribimos el siguiente comando

go mod init github.com/orlmonteverde/go-postgres-microblog

Eso creara un archivo llamado go.mod y el contenido de la carpeta deberia lucir de esta manera

.
└── go.mod

Si no han trabajando anteriormente con los Go Modules, les recomiendo revisar este articulo, si no desean hacerlo pueden simplemente seguir mis pasos o trabajar en su gopath.

Estructura del proyecto

Para este proyecto estaremos usando de forma un poco libre la estructura propuesta por golang-standards, no es la única estructura posible, pero es una que me resulta particularmente cómoda.

Directorios

cmd: para construir los ejecutables (aquí tendríamos tantos directorios con paquetes main como requiera el proyecto).
pkg: todos los paquetes que queremos compartir y que puedan ser reutilizables por otros proyectos.
internal: paquetes que solo competen al proyecto actual y que no queremos que sean utilizados fuera del mismo.

Creando directorios

Creamos los directorios de trabajo en la raíz del proyecto.

mkdir cmd pkg internal

Deberíamos tener una estructura similar a la siguiente.

.
├── cmd
├── go.mod
├── internal
└── pkg

Ahora dentro de cmd crearemos un directorio que contendrá el punto de inicio de nuestra aplicación, la llamare microblog, pueden llamarla como prefieran, pero para evitar confusiones seria recomendable que mantuvieran los nombres. De hecho, para evitar repetirme constantemente de ahora en adelante todos los nombres utilizados son recomendados, pero no obligatorios, a memos que se indique lo contrario.

mkdir cmd/microblog

Creamos un archivo llamado main.go dentro del directorio microblog .

touch cmd/microblog/main.go

El contenido de este archivo por el momento sera el siguiente

package main

import "fmt"

func main() {
    fmt.Println("Hello world!")
}

Ahora vamos a ejecutar nuestro programa para asegurarnos de que esta todo correcto hasta este punto. Desde la raíz del proyecto, ejecutamos el comando.

go build ./cmd/microblog

Ejecutado el comando deberíamos tener un binario llamado microblog (o microblog.exe si estas en windows). El cual podemos ejecutar.

./microblog

Y obtener una salida como esta.

Hello world!

Todo correcto hasta este punto, así que, comencemos a desarrollar nuestra API.

Modulo server

Lo primero que haremos sera crear un directorio server dentro del directorio internal, y luego crearemos un archivo llamado server.go dentro del mismo.

mkdir internal/server

touch internal/server/server.go

El contenido del archivo server.go sera inicialmente una estructura llamada Server que contendrá un puntero a la estructura http.Server de la biblioteca estándar.

// internal/server/server.go
package server

import "net/http"

// Server is a base server configuration.
type Server struct {
    server *http.Server
}

En este punto vamos a incluir, un paquete de terceros para manejar las rutas, en este caso chi, mediante go get, ejecutando el siguiente comando.

go get github.com/go-chi/chi

Hecho esto, se debió actualizar el archivo go.mod, ademas de crearse un archivo llamado go.sum, no nos preocuparemos de ellos porque no los vamos a editar, no directamente, pero si revisan el go.mod deberían ver el paquete chi que acabamos de descargar como un paquete requerido.

Ahora, regresando al archivo server.go, agregamos una función, que llamaremos New que recibe un string llamado port y retorna un puntero a la estructura Server y un error, dentro de esta función configuraremos el servidor y posteriormente lo retornaremos.

Desde el paquete chi estamos usando la función NewRouter, para obtener un nuevo Router y lo agregamos como Handler en la estructura http.Server, ademas de establecer el Addr con el port que recibe la función y limitar el tiempo de lectura y escritura a 10 segundos, para esto es necesario importar el paquete time de la biblioteca estándar.

// […]

// New inicialize a new server with configuration.
func New(port string) (*Server, error) {
    r := chi.NewRouter()

    serv := &http.Server{
        Addr:         ":" + port,
        Handler:      r,
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 10 * time.Second,
    }

    server := Server{server: serv}

    return &server, nil
}

Y ahora agregamos un par de métodos a la estructura Server, uno que llamaremos Close que utilizaremos para cerrar recursos antes de terminar con la ejecución del programa (por ejemplo, la conexión con la de base de datos, aunque de momento este método estará vacío) y uno llamado Start, en el que activamos el servidor.

// […]

// Close server resources.
func (serv *Server) Close() error {
    // TODO: add resource closure.
    return nil
}

// Start the server.
func (serv *Server) Start() {
    log.Printf("Server running on http://localhost%s", serv.server.Addr)
    log.Fatal(serv.server.ListenAndServe())
}

Volvamos al archivo main.go, para requerir el paquete server que acabamos de crear y pongamos a correr el servidor.

package main

import (
    "os"
    "os/signal"

    "log"

    "github.com/orlmonteverde/go-postgres-microblog/internal/server"
)

func main() {
    serv, err := server.New("8000")
    if err != nil {
        log.Fatal(err)
    }

    // start the server.
    go serv.Start()

    // Wait for an in interrupt.
    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt)
    <-c

    // Attempt a graceful shutdown.
    serv.Close()
}

Como se puede ver, estamos ejecutando el servidor dentro de una goroutine. Pero si lo dejamos así la función main llegara a su fin y la ejecución del programa terminara, y no es lo que buscamos.

Por ese motivo se agrega un channel que queda en espera de recibir un evento del sistema, una señal de interrupción (CTRL + C), asi el programa se mantendrá en ese punto hasta que ese evento ocurra y una vez que suceda ejecutara el resto de las instrucciones, en nuestro caso el método Close de nuestro Server.

Quizás te estés preguntando porque ejecutar el servidor en un goroutine separada, de no hacerlo no seria necesario crear el channel y demás. Es correcto, pero no tendríamos oportunidad de ejecutar otras instrucciones antes de que el programa finalice. Ahora ejecutamos nuevamente el programa.

go build ./cmd/microblog && ./microblog

Si vamos a http://localhost:8000 en nuestro navegador deberíamos ver un mensaje de “404 page not found”, que puede resultar un poco decepcionante, pero esta bien, significa que tenemos corriendo nuestro servidor, aunque aun no configuramos ninguna ruta, eso lo haremos mas adelante.

Variables de entorno

En el paso anterior, al inicializar el servidor pasamos el puerto directamente como un string, esto funciona bien, pero si quisiéramos cambiar el servidor tendríamos que modificar el código y volver a compilar, ademas de que en algunos casos no tenemos control sobre el puerto con el que funcionara el servidor, como es el caso de plataformas como Heroku.

Ademas de otras variables de configuración, que muy posiblemente queramos cambiar según el entorno en el que este corriendo nuestro programa, como la URI de la base de datos. En esos casos trabajar con variables de entorno podría ser una mejor opción, y eso haremos a continuación.

Primero crearemos un archivo llamado .env en la raíz de nuestro proyecto. Dentro de este archivo agregaremos las variables de entorno de forma =. En este caso solo nos interesa el puerto.

# .env
PORT=8000

Ahora solo debemos leer el valor de la variable de entorno PORT y pasarlo a la función New, así hagamos unos pequeños cambios al inicio de la función main en el archivo main.go.

// cmd/microblog/main.go
// […]
func main() {
    port := os.Getenv("PORT")
    serv, err := server.New(port)
        // [...]
}

Con esto podríamos cargar manualmente nuestras variables de entorno antes de ejecutar el programa y problema resulto, pero es repetitivo, aburrido y fácil de olvidar. Vamos a realizar esto de manera automática por medio de otro paquete de terceros, al igual que con chi tendremos que descargarlo con el comando go get. En este caso el paquete es GoDotEnv

go get github.com/joho/godotenv

Ahora que hemos descargado el paquete, regresamos al archivo main.go para utilizarlo, aunque existen varias formas de trabajar con este paquete y los invito a revisar su documentación, nosotros usaremos la mas sencilla, simplemente importando el paquete autoload. De esta forma, nuestro archivo main.go debería lucir similar al siguiente fragmento de codigo.

package main

import (
    "os"
    "os/signal"

    "log"

    "github.com/orlmonteverde/go-postgres-microblog/internal/server"

    _ "github.com/joho/godotenv/autoload"
)

func main() {
    port := os.Getenv("PORT")
    serv, err := server.New(port)
    if err != nil {
        log.Fatal(err)
    }

    // start the server.
    go serv.Start()

    // Wait for an in interrupt.
    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt)
    <-c

    // Attempt a graceful shutdown.
    serv.Close()
}

Con estos cambios, podemos modificar el valor de la variable de entornos tantas veces como sean necesarias y al ejecutar el programa este tomara el nuevo valor. Los invito a hacer la prueba.

Por ahora lo dejaremos hasta aquí, en el siguiente articulo continuaremos con el desarrollo de nuestra API. Les comparto el repositorio con el código del proyecto hasta el momento.