Целевым 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-канал с полезностями и уютный чат