この記事は、Wano Group Advent Calendar 2024の2日目の記事です。
1日目は、@_tachi_さんの、[Git] gitconfig 活用しよう
グループ会社のEDOCODEもAdvent Calendarをやっていますので、そちらもどうぞ。ちなみに、そっちにも実際のアクセスに近づけたAPIの負荷テストを行うという記事を本日書いています。
エラーレスポンス用のコードについて考える
500 エラーとか、400エラーとか、そういうのを返すコードです。基本的には、メッセージを変えるだけでコード自体は同じものになりがちで、コピペしまくる...ということになりがちですね。
また、どういうときに、500エラーがでて、どんなメッセージがでるのか、とか、もしかしたら資料として求められるかもしれません。
であれば、最初から資料として使えるファイル(TSV)をもとにコードを作れば良いんじゃない？と思いました。
で、後で変えたくなったときにも、TSVを変えるだけでコードも変更されるなら、コードとドキュメントに乖離もでないし良いんじゃない？ということでやってみました。
TSVを用意する
例えばこんな感じです。
name status_code take_error take_arg code message
Internal 500 1 0 5000 Internal Server Error
BadRequest 400 1 0 4000 Bad Request
InvalidApiKey 401 0 1 4000 Invalid API Key
UnauthorizeddApiKey 401 0 1 4001 Unauthorized API Key
MissingApiKey 400 0 0 4002 X-API-Key is missing in header
| 項目 | 意味 |
|---|---|
| name | Errorの名前 |
| status_code | HTTPレスポンスのステータスコード |
| take_error | errorを引数に取るか |
| take_arg | その他の引数を取るか |
| code | エラーレスポンスに含めるコード |
| message | エラーレスポンスに含めるメッセージ |
生成するコード
TSVファイルを読み込んでコードを自動生成するためのコードです。
package main
import (
"bytes"
"encoding/csv"
"log"
"os"
"regexp"
"text/template"
"github.com/jszwec/csvutil"
)
type Def struct {
Name string `csv:"name"`
TakeError int `csv:"take_error"`
TakeStringArg int `csv:"take_arg"`
StatusCode int `csv:"status_code"`
Code string `csv:"code"`
Message string `csv:"message"`
}
func main() {
tsvPath := os.Args[1]
goPath := os.Args[2]
defs, err := parseTsv[Def](tsvPath)
if err != nil {
log.Fatalf(err.Error())
}
data, err := os.ReadFile(goPath)
if err != nil {
log.Fatalf(err.Error())
}
content := string(data)
generated := ""
for _, def := range *defs {
templ := `const {{.Name}}StatusCode = {{.StatusCode}}
const {{.Name}}ErrorCode = "{{.Code}}"
func (c *CustomContext) Err{{.Name}}({{if .TakeStringArg}}message string{{end}}{{if .TakeError}}{{if .TakeStringArg}}, {{end}}e error{{end}}) error {
{{- if .TakeError}}
warnCalled(e)
{{- end -}}
{{- if or .TakeError .TakeStringArg -}}
{{if and .TakeError .TakeStringArg }}
{{- if and (gt .StatusCode 499) (lt .StatusCode 600) }}
// 適当に変えてください
if os.Getenv("APP_ENV") != "production" {
message = message + ", " + e.Error()
}
{{- end -}}
{{else if .TakeError}}
message := ": "+e.Error()
if config.NewAppEnv().IsProduction() {
message = ""
}
{{- else if .TakeStringArg }}
message = ": "+message
{{- end}}
{{- if and (gt .StatusCode 499) (lt .StatusCode 600) }}
log.Warn(message)
{{- end }}
return c.Status({{.Name}}StatusCode).JSON(NewErrorResponse({{.Name}}ErrorCode, "{{.Message}}"+message))
{{- else}}
return c.Status({{.Name}}StatusCode).JSON(NewErrorResponse({{.Name}}ErrorCode, "{{.Message}}"))
{{- end}}
}
`
t, err := template.New("goCode").Parse(templ)
if err != nil {
log.Panic(err)
}
initialBytes := []byte("")
buf := bytes.NewBuffer(initialBytes)
err = t.Execute(buf, def)
if err != nil {
log.Panic(err)
}
generated += buf.String()
}
re := regexp.MustCompile("(?s)(\n//go:generate go run .+?\n)(.*)$")
newContent := re.ReplaceAllString(content, "$1"+"\n"+generated+"\n")
err = os.WriteFile(goPath, []byte(newContent), 0644)
if err != nil {
log.Panicf("failed writing file: %s", err)
}
}
// このコードはutilsというpackageに入っていたもので、これ専用ではありません
func parseTsv[T any](path string) (*[]T, error) {
f, err := os.Open(path)
if err != nil {
return nil, err
}
defer f.Close()
csvReader := csv.NewReader(f)
csvReader.Comma = '\t'
dec, err := csvutil.NewDecoder(csvReader)
if err != nil {
log.Fatal(err)
}
defs := &[]T{}
if err := dec.Decode(&defs); err != nil {
return nil, err
}
return defs, nil
}
生成されるコードを含めるファイル
以下のファイル内に、下記を記載しています。
//go:generate go run ../../codegen/context-errors/main.go ../../docs/context-errors/errors.tsv ./generated_err.go
これで、go generateで生成できます。
package context
import (
"encoding/json"
"regexp"
"runtime"
"github.com/gofiber/fiber/v2/log"
)
type ErrorResponse struct {
Code string `json:"code"`
Message string `json:"message"`
}
// Implement MarshalJSON for ErrorResponse
func (e ErrorResponse) MarshalJSON() ([]byte, error) {
type Alias ErrorResponse
return json.Marshal(&struct {
Alias
}{
Alias: (Alias)(e),
})
}
func NewErrorResponse(code string, message string) ErrorResponse {
return ErrorResponse{
Code: code,
Message: message,
}
}
func warnCalled(e error) {
isErrOutputed := false
for i := range []int{2, 3, 4, 5} {
pc, file, line, ok := runtime.Caller(i)
if ok {
// `your-path`は適当に変えてください
r := regexp.MustCompile("^.+?your-path/")
file = r.ReplaceAllString(file, "your-path/")
fn := runtime.FuncForPC(pc)
if fn != nil {
if i == 2 {
isErrOutputed = true
log.Warnf("%s called from %s in %s at %d", e.Error(), fn.Name(), file, line)
} else {
log.Warnf(" called from %s in %s at %d", fn.Name(), file, line)
}
}
}
}
if !isErrOutputed {
log.Warn(e.Error())
}
}
// DON"T EDIT THE FLLOWING LINES
//go:generate go run ../../codegen/context-errors/main.go ../../docs/context-errors/errors.tsv ./generated_err.go
生成されたコード
以下のようなコードが生成されます。
const InternalStatusCode = 500
const InternalErrorCode = "5000"
func (c *CustomContext) ErrInternal(e error) error {
warnCalled(e)
message := ": " + e.Error()
if config.NewAppEnv().IsProduction() {
message = ""
}
log.Warn(message)
return c.Status(InternalStatusCode).JSON(NewErrorResponse(InternalErrorCode, "Internal Server Error"+message))
}
嬉しいところ
最初に書いた理由以外にも、いくつかあります。
テストに使える
例えば、テストを書いていたとして、(ないと思いますが)ErrInternalのHTTPのStatus Codeを変えたくなったとします。
そんな場合、テストコード上に、500 と書いて比較するのではなく、生成されたコードのconstのInternalStatusCodeを使えば、定義を変えてもテストは壊れません。
決めなきゃいけないことを後回しにできる
こういうコードとかは、後で変えてもそんなに問題がないけど、一旦決めとかないと開発進めにくいというものでもあるかなと思います。決めるものは少ないほうが良いので、一旦適当に決めておいて、後から真面目に考えて変更しても、破綻しないというのも、まぁ、良いんじゃないかなと思っています。
自動生成コードを変更すれば一気に変えられる
当たり前ですが、コピペだと面倒ですね。例えば、今回だと、以下のような変更をあと付けで行いました。
- productionならエラーメッセージをレスポンスに含めない
- 呼び出し元をログにだす
このような機能を一括で追加したいときにも便利かもしれません(関数化したら良いやんという話もあるかもしれません)。
終わり
以上、TSVからエラーレスポンス用のコードを自動生成する方法でした。ただ、一回適当に決めてしまうと、特に変えるモチベーションもわかず、そのまま使っているというオチ...だったりもします。
明日も...自分になってしまいましたが、「フルスクラッチでプロジェクトを始めるときにやっていること」になります。