Пишем обёртку для API Токийской фондовой биржи на Golang / Хабр

Целевым REST API будет jquants-api, описанный в предыдущей статье.

Я решил реализовать обёртку на Golang, что оказалось чрезвычайно быстро и удобно. В итоге я выполнил эту задачу за один вечер, а получившуюся Golang-обёртку с базовыми функциями загрузил на GitHub.

В этой статье я вкратце расскажу о процессе написания API и моих шагах по реализации проекта.

▍ Цели

Для начала перечислим задачи, которые нам предстоит выполнить:

Создать тест и поддерживающий код, проверяющий, что мы можем сохранять имя пользователя и пароль в файл edn, совместимый с форматом jquants-api-jvm.
Написать ещё один тест и поддерживающий код для получения токена обновления.
Написать ещё один тест и поддерживающий код для получения токена ID.
Написать ещё один тест и поддерживающий код с использованием токена ID для получения суточных значений.
Опубликовать нашу обёртку на GitHub.
Использовать нашу библиотеку Go в другой программе.

▍ Начнём с написания тестового случая, подготовки и сохранения структуры логина для доступа к API

Мы постоянно говорим о написании кода при помощи TDD, и теперь настало время его применить. Проверим, что у нас есть код для ввода и сохранения имени пользователя и пароля в файл edn, совместимый с форматом jquants-api-jvm.

В файле helper_test.go напишем скелет теста для функции PrepareLogin.

package jquants_api_go

import (
	"fmt"
	"os"
	"testing"
)

func TestPrepareLogin(t *testing.T) {
	PrepareLogin(os.Getenv("USERNAME"), os.Getenv("PASSWORD"))
}

Здесь мы берём USERNAME и PASSWORD из окружения при помощи os.GetEnv.

Запишем функцию подготовки в файл helper.go. Она будет делать следующее:

Получать в качестве параметров имя пользователя и пароль.
Создавать экземпляр структуры Login.
Структурировать его как содержимое файла EDN.

Структура Login будет выглядеть просто:

type Login struct {
    UserName string `edn:"mailaddress"`
    Password string `edn:"password"`
}

А вызов edn.Marshal будет создавать содержимое массива byte[], которое мы сможем записывать в файл, поэтому writeConfigFile просто будет вызывать os.WriteFile с массивом, возвращённым после упорядочивания в формат EDN.

func writeConfigFile(file string, content []byte) {
    os.WriteFile(getConfigFile(file), content, 0664)
}

Чтобы использовать библиотеку EDN, нам понадобится добавить её в файл go.mod:

require olympos.io/encoding/edn v0.0.0-20201019073823-d3554ca0b0a3

Перед запуском теста введите свои учётные данные jquants API:

export USERNAME="youremail@you.com"
export PASSWORD="yourpassword"

На этом этапе у вас уже должна быть возможность выполнять go test в папке проекта, а затем получать следующий результат:

PASS
ok      github.com/hellonico/jquants-api-go    1.012s

Также вы должны увидеть, что содержимое файла login.edn заполнено правильно:

cat ~/.config/jquants/login.edn

{:mailaddress "youremail@you.com" :password "yourpassword"}

▍ Использование Login для отправки HTTP-запроса jQuants API и получения RefreshToken

Второй функцией, которую надо протестировать, будет TestRefreshToken. Она отправляет HTTP-запрос POST с именем пользователя и паролем для получения в качестве ответа на вызов API токена обновления. Мы дополним файл helper_test.go новым тестовым случаем:

func TestRefreshToken(t *testing.T) {
    token, _ := GetRefreshToken()
    fmt.Printf("%s\n", token)
}

Функция GetRefreshToken будет выполнять следующее:

Загружать пользователя, сохранённого в файл ранее, и подготавливать его в виде данных JSON.
Подготавливать HTTP-запрос с URL и отформатированным в JSON пользователем в качестве содержимого body.
Отправлять HTTP-запрос.
API вернёт данные, которые будут храниться как структура RefreshToken.
После этого мы будем сохранять токен обновления как файл EDN.

Поддерживающая функция GetUser загружает содержимое файла, которое было записано на предыдущем этапе. У нас уже есть структура Login, и теперь мы просто используем edn.Unmarshall() с содержимым файла.

func GetUser() Login {
    s, _ := os.ReadFile(getConfigFile("login.edn"))
    var user Login
    edn.Unmarshal(s, &user)
    return user
}

Стоит заметить, что нам нужно считывать/записывать структуру Login в файл в формате EDN, а также при отправке HTTP-запроса нам требуется преобразовывать структуру в JSON.

То есть метаданные структуры Login нужно немного изменить:

type Login struct {
    UserName string `edn:"mailaddress" json:"mailaddress"`
    Password string `edn:"password" json:"password"`
}

Также нам нужно, чтобы новая структура считывала возвращённый API токен, то есть мы хотим хранить его в виде EDN, как это происходит со структурой Login:

type RefreshToken struct {
    RefreshToken string `edn:"refreshToken" json:"refreshToken"`
}

И теперь у нас есть все компоненты, чтобы написать функцию GetRefreshToken:

func GetRefreshToken() (RefreshToken, error) {
    // загрузка пользователя, ранее сохранённого в файл, и подготовка его в виде данных json
    var user = GetUser()
    data, err := json.Marshal(user)

    // подготовка http-запроса с url и пользователем, отформатированным в json, в качестве контента body
    url := fmt.Sprintf("%s/token/auth_user", BASE_URL)
    req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(data))
    
    // отправка запроса
    client := http.Client{}
    res, err := client.Do(req)

    // API вернёт данные, которые будут храниться в структуре RefreshToken
    var rt RefreshToken
    json.NewDecoder(res.Body).Decode(&rt)

    // также сохраним этот токен обновления в виде файла EDN
    encoded, err := edn.Marshal(&rt)
    writeConfigFile(REFRESH_TOKEN_FILE, encoded)

    return rt, err
}

Результат выполнения go test будет чуть более многословным, поскольку мы печатаем в стандартный вывод refreshToken, но тесты должны завершаться успешно!

{eyJjdHkiOiJKV1QiLC...}

PASS
ok      github.com/hellonico/jquants-api-go    3.231s

▍ Получение токена ID

Из Refresh Token можно получить IdToken, то есть токен, используемый для отправки запросов к jquants API. Процесс выполнения будет почти таким же, как у GetRefreshToken, и для его поддержки нам достаточно добавить новую структуру IdToken с необходимыми метаданными для преобразования в/из edn/json.

type IdToken struct {
    IdToken string `edn:"idToken" json:"idToken"`
}

Остальная часть кода на этот раз будет выглядеть так:

func GetIdToken() (IdToken, error) {
    var token = ReadRefreshToken()

    url := fmt.Sprintf("%s/token/auth_refresh?refreshtoken=%s", BASE_URL, token.RefreshToken)

    req, err := http.NewRequest(http.MethodPost, url, nil)
    client := http.Client{}
    res, err := client.Do(req)

    var rt IdToken
    json.NewDecoder(res.Body).Decode(&rt)

    encoded, err := edn.Marshal(&rt)
    writeConfigFile(ID_TOKEN_FILE, encoded)

    return rt, err
}

▍ Получение суточных котировок

Мы добрались до ядра кода обёртки, где будем использовать IdToken и запрашивать суточные котировки из HTTP API при помощи GET-запроса HTTP.

Поток выполнения кода для получения суточных котировок будет выглядеть так:

Как и ранее, считываем токен ID из файла EDN.
Подготавливаем целевой URL с кодом параметров и параметрами дат.
Отправляем HTTP-запрос, используя в качестве HTTP-заголовка idToken.
Парсим результат как структуру суточных котировок, которая будет являться срезом структур Quote.

Тестовый случай просто проверяет возврат ненулевого (nul) значения и печатает текущие котировки.

func TestDaily(t *testing.T) {
    var quotes = Daily("86970", "", "20220929", "20221003")
    
    if quotes.DailyQuotes == nil {
        t.Failed()
    }

    for _, quote := range quotes.DailyQuotes {
        fmt.Printf("%s,%f\n", quote.Date, quote.Close)
    }
}

Поддерживающий код для func Daily показан ниже:

func Daily(code string, date string, from string, to string) DailyQuotes {
    // чтение токена id
    idtoken := ReadIdToken()

    // подготовка url с параметрами
    baseUrl := fmt.Sprintf("%s/prices/daily_quotes?code=%s", BASE_URL, code)
    var url string
    if from != "" && to != "" {
        url = fmt.Sprintf("%s&from=%s&to=%s", baseUrl, from, to)
    } else {
        url = fmt.Sprintf("%s&date=%s", baseUrl, date)
    }
    // отправка HTTP-запроса с использованием idToken
    res := sendRequest(url, idtoken.IdToken)

    // парсинг результатов в виде суточных котировок
    var quotes DailyQuotes
    err_ := json.NewDecoder(res.Body).Decode(&quotes)
    Check(err_)
    return quotes
}

Теперь нам нужно заполнить пробелы:

Функции sendRequest требуется чуть больше подробностей.
Парсинг DailyQuotes на самом деле не так прост.

Давайте сначала разберёмся с sendRequest. Она задаёт заголовок при помощи http.Header. Обратите внимание, что здесь можно добавить любое количество заголовков. Затем она отправляет HTTP-запрос GET и возвращает ответ без изменений.

func sendRequest(url string, idToken string) *http.Response {

    req, _ := http.NewRequest(http.MethodGet, url, nil)
    req.Header = http.Header{
        "Authorization": {"Bearer " + idToken},
    }
    client := http.Client{}

    res, _ := client.Do(req)
    return res
}

Теперь перейдём к парсингу суточных котировок. Если вы пользуетесь редактором GoLand, то заметите, что при копировании и вставке содержимого JSON в файл на Go редактор спросит, нужно ли напрямую преобразовать JSON в код на Go!

Довольно неплохо.

type Quote struct {
    Code             string   `json:"Code"`
    Close            float64  `json:"Close"`
    Date             JSONTime `json:"Date"`
    AdjustmentHigh   float64  `json:"AdjustmentHigh"`
    Volume           float64  `json:"Volume"`
    TurnoverValue    float64  `json:"TurnoverValue"`
    AdjustmentClose  float64  `json:"AdjustmentClose"`
    AdjustmentLow    float64  `json:"AdjustmentLow"`
    Low              float64  `json:"Low"`
    High             float64  `json:"High"`
    Open             float64  `json:"Open"`
    AdjustmentOpen   float64  `json:"AdjustmentOpen"`
    AdjustmentFactor float64  `json:"AdjustmentFactor"`
    AdjustmentVolume float64  `json:"AdjustmentVolume"`
}

type DailyQuotes struct {
    DailyQuotes []Quote `json:"daily_quotes"`
}

Хотя стандартные параметры очень хороши, нам нужно настроить их, чтобы правильно преобразовать Dates обратно. Всё, что идёт далее, взято из поста о том, как преобразовывать даты JSON.

Тип JSONTime хранит свою внутреннюю дату как 64-битное integer, и мы добавляем JSONTime функции для преобразования/обратного преобразования JSONTime. Как видно, значение времени, получаемое из содержимого JSON, может быть или строкой, или integer.

type JSONTime int64

// String преобразует метку времени unix в string
func (t JSONTime) String() string {
    tm := t.Time()
    return fmt.Sprintf("\"%s\"", tm.Format("2006-01-02"))
}

// Time возвращает это значение в виде time.Time.
func (t JSONTime) Time() time.Time {
    return time.Unix(int64(t), 0)
}

// UnmarshalJSON производит обратное преобразование значений string и int JSON
func (t *JSONTime) UnmarshalJSON(buf []byte) error {
    s := bytes.Trim(buf, `"`)
    aa, _ := time.Parse("20060102", string(s))
    *t = JSONTime(aa.Unix())
    return nil
}

Изначально написанный тестовый случай теперь должен успешно завершаться с go test.

"2022-09-29",1952.000000
"2022-09-30",1952.500000
"2022-10-03",1946.000000
PASS
ok      github.com/hellonico/jquants-api-go    1.883s

Наш вспомогательный файл готов, теперь можно добавлять к нему CI.

▍ Конфигурация CircleCI

Конфигурация посимвольно схожа с официальной документацией CircleCI по тестированию с Golang.

Мы просто обновим образ Docker до 1.17.

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/go:1.17.9
    steps:
      - checkout
      - restore_cache:
          keys:
            - go-mod-v4-{{ checksum "go.sum" }}
      - run:
          name: Install Dependencies
          command: go get ./...
      - save_cache:
          key: go-mod-v4-{{ checksum "go.sum" }}
          paths:
            - "/go/pkg/mod"
      - run: go test -v

Теперь мы готовы настроить проект на CircleCI:

Требуемые параметры USERNAME и PASSWORD в helper_test.go can можно установить непосредственно из настроек Environment Variables проекта CircleCI:

Любой коммит в основную ветвь будет запускать сборку CircleCI (разумеется, её можно запускать и вручную), и если всё в порядке, вы должны увидеть успешно выполненные этапы:

Наша обёртка хорошо протестирована. Теперь приступим к её публикации.

▍ Публикация библиотеки на GitHub

При условии, что наш файл go.mod имеет следующее содержимое:

module github.com/hellonico/jquants-api-go

go 1.17

require olympos.io/encoding/edn v0.0.0-20201019073823-d3554ca0b0a3

Удобнее всего будет публиковать код при помощи git tag. Давайте создадим git tag и запушим его в GitHub следующим образом:

git tag v0.6.0
git push --tags

Теперь можно обеспечить зависимость отдельного проекта от нашей библиотеки, использовав её в go.mod.

require github.com/hellonico/jquants-api-go v0.6.0

▍ Использование библиотеки из внешней программы

Наша простая программа будет парсить параметры при помощи модуля flag, а затем вызывать различные функции, как это происходило в тестовых случаях для нашей обёртки.

package main

import (
    "flag"
    "fmt"
    jquants "github.com/hellonico/jquants-api-go"
)

func main() {

    code := flag.String("code", "86970", "Company Code")
    date := flag.String("date", "20220930", "Date of the quote")
    from := flag.String("from", "", "Start Date for date range")
    to := flag.String("to", "", "End Date for date range")
    refreshToken := flag.Bool("refresh", false, "refresh RefreshToken")
    refreshId := flag.Bool("id", false, "refresh IdToken")

    flag.Parse()

    if *refreshToken {
        jquants.GetRefreshToken()
    }
    if *refreshId {
        jquants.GetIdToken()
    }

    var quotes = jquants.Daily(*code, *date, *from, *to)

    fmt.Printf("[%d] Daily Quotes for %s \n", len(quotes.DailyQuotes), *code)
    for _, quote := range quotes.DailyQuotes {
        fmt.Printf("%s,%f\n", quote.Date, quote.Close)
    }

}

Мы можем создать CLI при помощи go build.

go build

И выполнить его с нужными параметрами:

Обновление токена ID.
Обновление токена обновления.
Получение суточных значений для записи с кодом 86970 с 20221005 по 20221010.

./jquants-example --id --refresh --from=20221005 --to=20221010 --code=86970

Code: 86970 and Date: 20220930 [From: 20221005 To: 20221010]
[3] Daily Quotes for 86970 
"2022-10-05",2016.500000
"2022-10-06",2029.000000
"2022-10-07",1992.500000

Отличная работа. Мы оставим пользователю задачу написания statements и listedInfo, являющихся частью JQuants API, но пока не реализованных в этой оболочке.

Telegram-канал с полезностями и уютный чат

Пишем обёртку для API Токийской фондовой биржи на Golang