Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 6 additions & 31 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,38 +25,13 @@ make test-e2e # E2Eテスト(JQUANTS_API_KEY が必要)
make test-run TEST=TestQuotesService_GetDailyQuotes # 特定のテスト
```

## ディレクトリ構造

- `client/`: HTTPクライアント(認証、キャッシュ)とモック
- `types/`: カスタム型(JSONの不整合な型を処理)
- `docs/v2/`: v2 APIドキュメント
- `test/e2e/`: E2Eテスト

## 新しいAPIサービスの追加方法

1. 新しいサービスファイルを作成(例:`new_service.go`)
2. サービス構造体とメソッドを実装
3. `jquants.go`の`JQuantsAPI`構造体に新サービスを追加
4. 対応するテストファイルを作成(例:`new_service_test.go`)
5. `docs/v2/`ディレクトリにドキュメントを追加

## テスト実装のパターン

```go
func TestService_Method(t *testing.T) {
mockClient := &client.MockClient{
DoFunc: func(req *http.Request) (*http.Response, error) {
// モックレスポンスを返す
},
}
service := &Service{client: mockClient}
// テスト実行
}
```
## 新しいAPIサービスの追加時の注意

- `jquants.go`の`JQuantsAPI`構造体への登録を忘れない(忘れてもコンパイルは通る)
- `docs/v2/`ディレクトリにドキュメントを追加する

## 実装上の注意点

1. **nil安全性**: APIレスポンスの欠損フィールドはポインタで表現
2. **エラーハンドリング**: 一貫したエラーラップとコンテキスト情報の付与
3. **型変換**: `types`パッケージのカスタム型を使用してJSONの不整合を処理
4. **定数定義**: 市場区分コード、業種コード、開示書類種別などは定数として定義済み
2. **型変換**: APIはJSONの型を不整合に返すことがあるため、`types`パッケージのカスタム型で処理
3. **定数定義**: 市場区分コード、業種コード、開示書類種別などは定数として定義済み(再定義しない)
31 changes: 17 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ go get github.com/utahta/jquants
package main

import (
"context"
"fmt"
"log"

Expand All @@ -41,7 +42,8 @@ func main() {
jq := jquants.NewJQuantsAPI(httpClient)

// 株価データを取得
quotes, err := jq.Quotes.GetDailyQuotesByCode("7203") // トヨタ自動車
ctx := context.Background()
quotes, err := jq.Quotes.GetDailyQuotesByCode(ctx, "7203") // トヨタ自動車
if err != nil {
log.Fatal(err)
}
Expand Down Expand Up @@ -91,6 +93,7 @@ size := httpClient.CacheSize()
- キャッシュはGETリクエストのみに適用されます
- キャッシュキーはリクエストパス(クエリパラメータ含む)で区別されます
- 同時リクエストの重複排除(singleflight)により効率的に動作します
- 重複排除の待機中にコンテキストをキャンセルした場合、その呼び出し元だけが即座にエラーで戻り、進行中のリクエスト自体は完了してキャッシュに保存されます
- キャッシュはクライアントインスタンスの生存期間のみ有効です

## 利用可能なAPI
Expand Down Expand Up @@ -127,15 +130,15 @@ size := httpClient.CacheSize()

```go
// 特定銘柄の直近データ
quotes, err := jq.Quotes.GetDailyQuotesByCode("7203")
quotes, err := jq.Quotes.GetDailyQuotesByCode(ctx, "7203")

// 日付範囲指定
params := jquants.DailyQuotesParams{
Code: "7203",
From: "2024-01-01",
To: "2024-01-31",
}
response, err := jq.Quotes.GetDailyQuotes(params)
response, err := jq.Quotes.GetDailyQuotes(ctx, params)

// v2 APIでは短縮フィールド名を使用
for _, q := range response.Data {
Expand All @@ -148,14 +151,14 @@ for _, q := range response.Data {

```go
// 全銘柄を取得
companies, err := jq.Listed.GetInfo()
companies, err := jq.Listed.GetAllListedInfo(ctx)

// 特定銘柄の情報を取得
company, err := jq.Listed.GetInfoByCode("7203")
fmt.Printf("企業名: %s\n", company.Name)
companies, err := jq.Listed.GetListedInfoByCode(ctx, "7203")
fmt.Printf("企業名: %s\n", companies[0].Name)

// 市場区分で絞り込み(定数を使用)
primeCompanies, err := jq.Listed.GetListedByMarket(jquants.MarketPrime, "")
primeCompanies, err := jq.Listed.GetListedByMarket(ctx, jquants.MarketPrime, "")
for _, company := range primeCompanies {
fmt.Printf("%s (%s) - %s\n", company.Name, company.Code, company.MktName)
}
Expand All @@ -165,13 +168,13 @@ for _, company := range primeCompanies {

```go
// 最新の財務情報
statement, err := jq.Statements.GetLatestStatements("7203")
statement, err := jq.Statements.GetLatestStatements(ctx, "7203")
if statement.NetSales != nil {
fmt.Printf("売上高: %.0f円\n", *statement.NetSales)
}

// 特定日の財務情報
statements, err := jq.Statements.GetStatementsByDate("2024-01-15")
statements, err := jq.Statements.GetStatementsByDate(ctx, "2024-01-15")

// 開示書類種別での絞り込み
for _, stmt := range statements {
Expand All @@ -189,10 +192,10 @@ for _, stmt := range statements {

```go
// 銘柄コードで取得
data, err := jq.DailyMarginInterest.GetDailyMarginInterestByCode("13260")
data, err := jq.DailyMarginInterest.GetDailyMarginInterestByCode(ctx, "13260")

// 公表日で取得
data, err := jq.DailyMarginInterest.GetDailyMarginInterestByDate("20240208")
data, err := jq.DailyMarginInterest.GetDailyMarginInterestByDate(ctx, "20240208")

// 公表理由の確認
for _, d := range data {
Expand All @@ -212,13 +215,13 @@ params := jquants.DailyQuotesParams{
}

// 最初のページ
response, err := jq.Quotes.GetDailyQuotes(params)
response, err := jq.Quotes.GetDailyQuotes(ctx, params)
quotes := response.Data

// 次のページがある場合
if response.PaginationKey != "" {
params.PaginationKey = response.PaginationKey
nextResponse, err := jq.Quotes.GetDailyQuotes(params)
nextResponse, err := jq.Quotes.GetDailyQuotes(ctx, params)
quotes = append(quotes, nextResponse.Data...)
}
```
Expand Down Expand Up @@ -313,7 +316,7 @@ cd cmd/gitbook2md && go build
## エラーハンドリング

```go
quotes, err := jq.Quotes.GetDailyQuotesByCode("9999")
quotes, err := jq.Quotes.GetDailyQuotesByCode(ctx, "9999")
if err != nil {
// APIエラーの詳細を取得
if apiErr, ok := err.(*client.APIError); ok {
Expand Down
13 changes: 7 additions & 6 deletions announcement.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package jquants

import (
"context"
"fmt"

"github.com/utahta/jquants/client"
Expand Down Expand Up @@ -48,15 +49,15 @@ type AnnouncementParams struct {
// 3月期・9月期決算会社のみ対応しています。
// パラメータ:
// - params: ページネーション用のパラメータ(オプション)
func (s *AnnouncementService) GetAnnouncement(params AnnouncementParams) (*AnnouncementResponse, error) {
func (s *AnnouncementService) GetAnnouncement(ctx context.Context, params AnnouncementParams) (*AnnouncementResponse, error) {
path := "/equities/earnings-calendar"

if params.PaginationKey != "" {
path += fmt.Sprintf("?pagination_key=%s", params.PaginationKey)
}

var resp AnnouncementResponse
if err := s.client.DoRequest("GET", path, nil, &resp); err != nil {
if err := s.client.DoRequest(ctx, "GET", path, nil, &resp); err != nil {
return nil, fmt.Errorf("failed to get announcement: %w", err)
}

Expand All @@ -65,7 +66,7 @@ func (s *AnnouncementService) GetAnnouncement(params AnnouncementParams) (*Annou

// GetAllAnnouncements は翌営業日の全決算発表予定を取得します。
// ページネーションを使用して全データを取得します。
func (s *AnnouncementService) GetAllAnnouncements() ([]Announcement, error) {
func (s *AnnouncementService) GetAllAnnouncements(ctx context.Context) ([]Announcement, error) {
var allAnnouncements []Announcement
paginationKey := ""

Expand All @@ -74,7 +75,7 @@ func (s *AnnouncementService) GetAllAnnouncements() ([]Announcement, error) {
PaginationKey: paginationKey,
}

resp, err := s.GetAnnouncement(params)
resp, err := s.GetAnnouncement(ctx, params)
if err != nil {
return nil, err
}
Expand All @@ -93,8 +94,8 @@ func (s *AnnouncementService) GetAllAnnouncements() ([]Announcement, error) {

// GetAnnouncementByCode は指定銘柄の決算発表予定を取得します。
// 翌営業日に決算発表予定がある場合のみ取得できます。
func (s *AnnouncementService) GetAnnouncementByCode(code string) (*Announcement, error) {
announcements, err := s.GetAllAnnouncements()
func (s *AnnouncementService) GetAnnouncementByCode(ctx context.Context, code string) (*Announcement, error) {
announcements, err := s.GetAllAnnouncements(ctx)
if err != nil {
return nil, err
}
Expand Down
11 changes: 6 additions & 5 deletions announcement_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package jquants

import (
"context"
"fmt"
"testing"

Expand Down Expand Up @@ -60,7 +61,7 @@ func TestAnnouncementService_GetAnnouncement(t *testing.T) {
mockClient.SetResponse("GET", tt.wantPath, mockResponse)

// Test
resp, err := service.GetAnnouncement(tt.params)
resp, err := service.GetAnnouncement(context.Background(), tt.params)
if err != nil {
t.Errorf("GetAnnouncement failed: %v", err)
}
Expand Down Expand Up @@ -135,7 +136,7 @@ func TestAnnouncementService_GetAllAnnouncements(t *testing.T) {
mockClient.SetResponse("GET", "/equities/earnings-calendar?pagination_key=next_key", mockResponse2)

// Test
announcements, err := service.GetAllAnnouncements()
announcements, err := service.GetAllAnnouncements(context.Background())
if err != nil {
t.Errorf("GetAllAnnouncements failed: %v", err)
}
Expand Down Expand Up @@ -188,7 +189,7 @@ func TestAnnouncementService_GetAnnouncementByCode(t *testing.T) {
mockClient.SetResponse("GET", "/equities/earnings-calendar", mockResponse)

// Test
announcement, err := service.GetAnnouncementByCode("7203")
announcement, err := service.GetAnnouncementByCode(context.Background(), "7203")
if err != nil {
t.Errorf("GetAnnouncementByCode failed: %v", err)
}
Expand Down Expand Up @@ -230,7 +231,7 @@ func TestAnnouncementService_GetAnnouncementByCode_NotFound(t *testing.T) {
mockClient.SetResponse("GET", "/equities/earnings-calendar", mockResponse)

// Test
_, err := service.GetAnnouncementByCode("7203")
_, err := service.GetAnnouncementByCode(context.Background(), "7203")
if err == nil {
t.Errorf("Expected error for non-existent code, got nil")
}
Expand All @@ -245,7 +246,7 @@ func TestAnnouncementService_GetAnnouncement_Error(t *testing.T) {
mockClient.SetError("GET", "/equities/earnings-calendar", fmt.Errorf("API error"))

// Test
_, err := service.GetAnnouncement(AnnouncementParams{})
_, err := service.GetAnnouncement(context.Background(), AnnouncementParams{})
if err == nil {
t.Errorf("Expected error, got nil")
}
Expand Down
13 changes: 7 additions & 6 deletions breakdown.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package jquants

import (
"context"
"encoding/json"
"fmt"
"time"
Expand Down Expand Up @@ -143,7 +144,7 @@ func (r *BreakdownResponse) UnmarshalJSON(data []byte) error {
//
// 注意: このAPIはプレミアムプラン専用です。
// スタンダードプラン以下では "This API is not available on your subscription" エラーが返されます。
func (s *BreakdownService) GetBreakdown(params BreakdownParams) (*BreakdownResponse, error) {
func (s *BreakdownService) GetBreakdown(ctx context.Context, params BreakdownParams) (*BreakdownResponse, error) {
path := "/markets/breakdown"

query := "?"
Expand All @@ -168,7 +169,7 @@ func (s *BreakdownService) GetBreakdown(params BreakdownParams) (*BreakdownRespo
}

var resp BreakdownResponse
if err := s.client.DoRequest("GET", path, nil, &resp); err != nil {
if err := s.client.DoRequest(ctx, "GET", path, nil, &resp); err != nil {
return nil, fmt.Errorf("failed to get breakdown: %w", err)
}

Expand All @@ -180,7 +181,7 @@ func (s *BreakdownService) GetBreakdown(params BreakdownParams) (*BreakdownRespo
//
// 注意: このAPIはプレミアムプラン専用です。
// スタンダードプラン以下では "This API is not available on your subscription" エラーが返されます。
func (s *BreakdownService) GetBreakdownByCode(code string, days int) ([]Breakdown, error) {
func (s *BreakdownService) GetBreakdownByCode(ctx context.Context, code string, days int) ([]Breakdown, error) {
to := time.Now()
from := to.AddDate(0, 0, -days)

Expand All @@ -195,7 +196,7 @@ func (s *BreakdownService) GetBreakdownByCode(code string, days int) ([]Breakdow
PaginationKey: paginationKey,
}

resp, err := s.GetBreakdown(params)
resp, err := s.GetBreakdown(ctx, params)
if err != nil {
return nil, err
}
Expand All @@ -214,7 +215,7 @@ func (s *BreakdownService) GetBreakdownByCode(code string, days int) ([]Breakdow

// GetBreakdownByDate は指定日の全銘柄の売買内訳データを取得します。
// ページネーションを使用して大量データを分割取得します。
func (s *BreakdownService) GetBreakdownByDate(date string) ([]Breakdown, error) {
func (s *BreakdownService) GetBreakdownByDate(ctx context.Context, date string) ([]Breakdown, error) {
var allBreakdown []Breakdown
paginationKey := ""

Expand All @@ -224,7 +225,7 @@ func (s *BreakdownService) GetBreakdownByDate(date string) ([]Breakdown, error)
PaginationKey: paginationKey,
}

resp, err := s.GetBreakdown(params)
resp, err := s.GetBreakdown(ctx, params)
if err != nil {
return nil, err
}
Expand Down
9 changes: 5 additions & 4 deletions breakdown_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package jquants

import (
"context"
"fmt"
"testing"
"time"
Expand Down Expand Up @@ -88,7 +89,7 @@ func TestBreakdownService_GetBreakdown(t *testing.T) {
mockClient.SetResponse("GET", tt.wantPath, mockResponse)

// Execute
resp, err := service.GetBreakdown(tt.params)
resp, err := service.GetBreakdown(context.Background(), tt.params)

// Verify
if err != nil {
Expand Down Expand Up @@ -136,7 +137,7 @@ func TestBreakdownService_GetBreakdownByCode(t *testing.T) {
mockClient.SetResponse("GET", expectedPath, mockResponse)

// Execute
breakdown, err := service.GetBreakdownByCode("7203", 30)
breakdown, err := service.GetBreakdownByCode(context.Background(), "7203", 30)

// Verify
if err != nil {
Expand Down Expand Up @@ -188,7 +189,7 @@ func TestBreakdownService_GetBreakdownByDate(t *testing.T) {
mockClient.SetResponse("GET", "/markets/breakdown?date=20240101&pagination_key=next_page_key", mockResponse2)

// Execute
breakdown, err := service.GetBreakdownByDate("20240101")
breakdown, err := service.GetBreakdownByDate(context.Background(), "20240101")

// Verify
if err != nil {
Expand All @@ -208,7 +209,7 @@ func TestBreakdownService_GetBreakdown_Error(t *testing.T) {
mockClient.SetError("GET", "/markets/breakdown?code=7203", fmt.Errorf("unauthorized"))

// Execute
_, err := service.GetBreakdown(BreakdownParams{Code: "7203"})
_, err := service.GetBreakdown(context.Background(), BreakdownParams{Code: "7203"})

// Verify
if err == nil {
Expand Down
Loading
Loading