feat: 初始化 cryptoHermes 行情网关 v1 MVP + harness 工程文档
Binance USDⓈ-M Futures 行情网关，给上游 Hermes 量化分析引擎提供单一聚合 接口 /v1/market/context（K 线 + funding + OI + 多空比 + taker volume）。 只读公共行情，不下单、不接私钥、不查账户。 ## v1 实现范围（Milestone 1-5） - Clean Architecture 4 层（controller/usecase/repo/entity），接口边界在 internal/usecase/ports.go - Binance Futures REST client（K 线 / ticker24h / funding / OI / 多空比 / taker volume 共 9 个接口），全链路 string 价格避免 float64 精度问题 - TimescaleDB 5 张 hypertable（market_klines / funding_rates / open_interest / long_short_ratio / taker_buy_sell_volume），主键含 时间维度，UpsertMany 幂等 - robfig/cron 定时采集（15m/1h/4h/1d/1w 多周期 K 线 + 衍生品 15 分钟 落库），未收线 K 线 (close_time > now) 由 mapper/repo 双重过滤 - pkg/httpclient 统一限流（默认 20 req/s, burst 40）+ 重试，避免触发 Binance 2400 weight/min IP 上限 - /v1/market/context 聚合接口：errgroup 并发拉 snapshot/funding/OI，DB K 线不足 200 根回源 Binance 异步补 - cmd/backfill CLI 支持指定 from/to 大段回填（Binance 历史 OI / 多空比 官方只保留 30 天，必须自己存） - Docker Compose + Makefile + golang-migrate，本地一键启 技术指标（support/resistance/Vegas/箱体）留待 v2，技术段返回空对象 + warning 占位。 ## Harness 工程文档 - AGENTS.md — AI agent 工作速查（10 个章节） - ai/project-map.md — 仓库结构、扩展点、控制流 - ai/risk-guardrails.md — G1-G10 守卫规则（每条带可机械验证命令） - ai/adr/0001-architecture-foundations.md — 9 条架构基础决策 - ai/task-templates.md — 6 种任务契约模板 - ai/harness-health.md — 当前 harness 健康度评估 3 个 grep 守卫已验证通过：controller / usecase 无具体实现依赖，全项目 无私钥/签名字段。
This commit is contained in:
dela
72
internal/repo/webapi/binance/client.go
Normal file
72
internal/repo/webapi/binance/client.go
Normal file
@@ -0,0 +1,72 @@
|
||||
package binance
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"time"
|
||||
|
||||
"cryptoHermes/pkg/httpclient"
|
||||
)
|
||||
|
||||
const sourceName = "binance"
|
||||
|
||||
type Client struct {
|
||||
http *httpclient.Client
|
||||
source string
|
||||
}
|
||||
|
||||
type ClientOptions struct {
|
||||
BaseURL string
|
||||
Timeout time.Duration
|
||||
RetryCount int
|
||||
RPS float64
|
||||
Burst int
|
||||
}
|
||||
|
||||
func NewClient(opts ClientOptions) *Client {
|
||||
return &Client{
|
||||
http: httpclient.New(httpclient.Options{
|
||||
BaseURL: opts.BaseURL,
|
||||
Timeout: opts.Timeout,
|
||||
RetryCount: opts.RetryCount,
|
||||
RPS: opts.RPS,
|
||||
Burst: opts.Burst,
|
||||
}),
|
||||
source: sourceName,
|
||||
}
|
||||
}
|
||||
|
||||
type ExternalAPIError struct {
|
||||
Source string
|
||||
Path string
|
||||
StatusCode int
|
||||
Message string
|
||||
}
|
||||
|
||||
func (e *ExternalAPIError) Error() string {
|
||||
return fmt.Sprintf("%s %s status=%d: %s", e.Source, e.Path, e.StatusCode, e.Message)
|
||||
}
|
||||
|
||||
func (c *Client) get(ctx context.Context, path string, q url.Values, out any) error {
|
||||
status, body, _, err := c.http.Do(ctx, httpclient.Request{
|
||||
Method: http.MethodGet,
|
||||
Path: path,
|
||||
Query: q,
|
||||
})
|
||||
if err != nil {
|
||||
return &ExternalAPIError{Source: c.source, Path: path, StatusCode: 0, Message: err.Error()}
|
||||
}
|
||||
if status >= 400 {
|
||||
return &ExternalAPIError{Source: c.source, Path: path, StatusCode: status, Message: string(body)}
|
||||
}
|
||||
if out == nil {
|
||||
return nil
|
||||
}
|
||||
if err := json.Unmarshal(body, out); err != nil {
|
||||
return &ExternalAPIError{Source: c.source, Path: path, StatusCode: status, Message: "decode: " + err.Error()}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
116
internal/repo/webapi/binance/derivatives.go
Normal file
116
internal/repo/webapi/binance/derivatives.go
Normal file
@@ -0,0 +1,116 @@
|
||||
package binance
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/url"
|
||||
"strconv"
|
||||
|
||||
"cryptoHermes/internal/entity"
|
||||
)
|
||||
|
||||
func (c *Client) GetCurrentFunding(ctx context.Context, symbol string) (*entity.FundingRate, error) {
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
var dto premiumIndexDTO
|
||||
if err := c.get(ctx, "/fapi/v1/premiumIndex", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapPremiumIndex(&dto), nil
|
||||
}
|
||||
|
||||
func (c *Client) GetFundingHistory(ctx context.Context, symbol string, limit int) ([]entity.FundingRate, error) {
|
||||
if limit <= 0 {
|
||||
limit = 100
|
||||
}
|
||||
if limit > 1000 {
|
||||
limit = 1000
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
q.Set("limit", strconv.Itoa(limit))
|
||||
var dto []fundingRateDTO
|
||||
if err := c.get(ctx, "/fapi/v1/fundingRate", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapFundingHistory(dto), nil
|
||||
}
|
||||
|
||||
func (c *Client) GetCurrentOpenInterest(ctx context.Context, symbol string) (*entity.OpenInterest, error) {
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
var dto openInterestDTO
|
||||
if err := c.get(ctx, "/fapi/v1/openInterest", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapOpenInterest(&dto, "current"), nil
|
||||
}
|
||||
|
||||
func (c *Client) GetOpenInterestHistory(ctx context.Context, symbol, period string, limit int) ([]entity.OpenInterest, error) {
|
||||
if limit <= 0 {
|
||||
limit = 30
|
||||
}
|
||||
if limit > 500 {
|
||||
limit = 500
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
q.Set("period", period)
|
||||
q.Set("limit", strconv.Itoa(limit))
|
||||
var dto []openInterestHistDTO
|
||||
if err := c.get(ctx, "/futures/data/openInterestHist", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapOpenInterestHistory(dto, period), nil
|
||||
}
|
||||
|
||||
func (c *Client) GetGlobalLongShortRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error) {
|
||||
dto, err := c.fetchLongShort(ctx, "/futures/data/globalLongShortAccountRatio", symbol, period, limit)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapLongShort(dto, period, entity.RatioTypeGlobalAccount), nil
|
||||
}
|
||||
|
||||
func (c *Client) GetTopTraderPositionRatio(ctx context.Context, symbol, period string, limit int) ([]entity.LongShortRatio, error) {
|
||||
dto, err := c.fetchLongShort(ctx, "/futures/data/topLongShortPositionRatio", symbol, period, limit)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapLongShort(dto, period, entity.RatioTypeTopTraderPosition), nil
|
||||
}
|
||||
|
||||
func (c *Client) fetchLongShort(ctx context.Context, path, symbol, period string, limit int) ([]longShortRatioDTO, error) {
|
||||
if limit <= 0 {
|
||||
limit = 30
|
||||
}
|
||||
if limit > 500 {
|
||||
limit = 500
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
q.Set("period", period)
|
||||
q.Set("limit", strconv.Itoa(limit))
|
||||
var dto []longShortRatioDTO
|
||||
if err := c.get(ctx, path, q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return dto, nil
|
||||
}
|
||||
|
||||
func (c *Client) GetTakerBuySellVolume(ctx context.Context, symbol, period string, limit int) ([]entity.TakerBuySellVolume, error) {
|
||||
if limit <= 0 {
|
||||
limit = 30
|
||||
}
|
||||
if limit > 500 {
|
||||
limit = 500
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
q.Set("period", period)
|
||||
q.Set("limit", strconv.Itoa(limit))
|
||||
var dto []takerVolumeDTO
|
||||
if err := c.get(ctx, "/futures/data/takerlongshortRatio", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapTakerVolume(dto, symbol, period), nil
|
||||
}
|
||||
60
internal/repo/webapi/binance/dto.go
Normal file
60
internal/repo/webapi/binance/dto.go
Normal file
@@ -0,0 +1,60 @@
|
||||
package binance
|
||||
|
||||
type tickerDTO struct {
|
||||
Symbol string `json:"symbol"`
|
||||
LastPrice string `json:"lastPrice"`
|
||||
PriceChange string `json:"priceChange"`
|
||||
PriceChangePercent string `json:"priceChangePercent"`
|
||||
HighPrice string `json:"highPrice"`
|
||||
LowPrice string `json:"lowPrice"`
|
||||
Volume string `json:"volume"`
|
||||
QuoteVolume string `json:"quoteVolume"`
|
||||
OpenTime int64 `json:"openTime"`
|
||||
CloseTime int64 `json:"closeTime"`
|
||||
}
|
||||
|
||||
type premiumIndexDTO struct {
|
||||
Symbol string `json:"symbol"`
|
||||
MarkPrice string `json:"markPrice"`
|
||||
IndexPrice string `json:"indexPrice"`
|
||||
LastFundingRate string `json:"lastFundingRate"`
|
||||
NextFundingTime int64 `json:"nextFundingTime"`
|
||||
Time int64 `json:"time"`
|
||||
}
|
||||
|
||||
type fundingRateDTO struct {
|
||||
Symbol string `json:"symbol"`
|
||||
FundingTime int64 `json:"fundingTime"`
|
||||
FundingRate string `json:"fundingRate"`
|
||||
MarkPrice string `json:"markPrice"`
|
||||
}
|
||||
|
||||
type openInterestDTO struct {
|
||||
OpenInterest string `json:"openInterest"`
|
||||
Symbol string `json:"symbol"`
|
||||
Time int64 `json:"time"`
|
||||
}
|
||||
|
||||
type openInterestHistDTO struct {
|
||||
Symbol string `json:"symbol"`
|
||||
SumOpenInterest string `json:"sumOpenInterest"`
|
||||
SumOpenInterestValue string `json:"sumOpenInterestValue"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
type longShortRatioDTO struct {
|
||||
Symbol string `json:"symbol"`
|
||||
LongShortRatio string `json:"longShortRatio"`
|
||||
LongAccount string `json:"longAccount"`
|
||||
ShortAccount string `json:"shortAccount"`
|
||||
LongPosition string `json:"longPosition"`
|
||||
ShortPosition string `json:"shortPosition"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
type takerVolumeDTO struct {
|
||||
BuySellRatio string `json:"buySellRatio"`
|
||||
BuyVol string `json:"buyVol"`
|
||||
SellVol string `json:"sellVol"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
170
internal/repo/webapi/binance/mapper.go
Normal file
170
internal/repo/webapi/binance/mapper.go
Normal file
@@ -0,0 +1,170 @@
|
||||
package binance
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
"cryptoHermes/internal/entity"
|
||||
)
|
||||
|
||||
func parseKlineRow(symbol, interval string, row []any) (entity.Kline, error) {
|
||||
if len(row) < 12 {
|
||||
return entity.Kline{}, fmt.Errorf("binance kline row has %d fields, expected >=12", len(row))
|
||||
}
|
||||
openTime, err := toInt64(row[0])
|
||||
if err != nil {
|
||||
return entity.Kline{}, fmt.Errorf("openTime: %w", err)
|
||||
}
|
||||
closeTime, err := toInt64(row[6])
|
||||
if err != nil {
|
||||
return entity.Kline{}, fmt.Errorf("closeTime: %w", err)
|
||||
}
|
||||
tradeCount, err := toInt64(row[8])
|
||||
if err != nil {
|
||||
return entity.Kline{}, fmt.Errorf("tradeCount: %w", err)
|
||||
}
|
||||
|
||||
open, _ := row[1].(string)
|
||||
high, _ := row[2].(string)
|
||||
low, _ := row[3].(string)
|
||||
closeP, _ := row[4].(string)
|
||||
volume, _ := row[5].(string)
|
||||
quoteVol, _ := row[7].(string)
|
||||
takerBase, _ := row[9].(string)
|
||||
takerQuote, _ := row[10].(string)
|
||||
|
||||
nowMs := time.Now().UnixMilli()
|
||||
return entity.Kline{
|
||||
Source: sourceName,
|
||||
Symbol: symbol,
|
||||
Interval: interval,
|
||||
OpenTime: openTime,
|
||||
CloseTime: closeTime,
|
||||
Open: open,
|
||||
High: high,
|
||||
Low: low,
|
||||
Close: closeP,
|
||||
Volume: volume,
|
||||
QuoteVolume: quoteVol,
|
||||
TradeCount: tradeCount,
|
||||
TakerBuyBaseVolume: takerBase,
|
||||
TakerBuyQuoteVolume: takerQuote,
|
||||
IsClosed: closeTime < nowMs,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func toInt64(v any) (int64, error) {
|
||||
switch x := v.(type) {
|
||||
case float64:
|
||||
return int64(x), nil
|
||||
case int64:
|
||||
return x, nil
|
||||
case int:
|
||||
return int64(x), nil
|
||||
default:
|
||||
return 0, fmt.Errorf("unexpected type %T", v)
|
||||
}
|
||||
}
|
||||
|
||||
func mapTicker(d *tickerDTO) *entity.Ticker24h {
|
||||
return &entity.Ticker24h{
|
||||
Symbol: d.Symbol,
|
||||
LastPrice: d.LastPrice,
|
||||
PriceChange: d.PriceChange,
|
||||
PriceChangePercent: d.PriceChangePercent,
|
||||
HighPrice: d.HighPrice,
|
||||
LowPrice: d.LowPrice,
|
||||
Volume: d.Volume,
|
||||
QuoteVolume: d.QuoteVolume,
|
||||
OpenTime: d.OpenTime,
|
||||
CloseTime: d.CloseTime,
|
||||
}
|
||||
}
|
||||
|
||||
func mapPremiumIndex(d *premiumIndexDTO) *entity.FundingRate {
|
||||
return &entity.FundingRate{
|
||||
Source: sourceName,
|
||||
Symbol: d.Symbol,
|
||||
FundingTime: d.NextFundingTime,
|
||||
FundingRate: d.LastFundingRate,
|
||||
MarkPrice: d.MarkPrice,
|
||||
}
|
||||
}
|
||||
|
||||
func mapFundingHistory(d []fundingRateDTO) []entity.FundingRate {
|
||||
out := make([]entity.FundingRate, 0, len(d))
|
||||
for _, x := range d {
|
||||
out = append(out, entity.FundingRate{
|
||||
Source: sourceName,
|
||||
Symbol: x.Symbol,
|
||||
FundingTime: x.FundingTime,
|
||||
FundingRate: x.FundingRate,
|
||||
MarkPrice: x.MarkPrice,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func mapOpenInterest(d *openInterestDTO, period string) *entity.OpenInterest {
|
||||
return &entity.OpenInterest{
|
||||
Source: sourceName,
|
||||
Symbol: d.Symbol,
|
||||
Period: period,
|
||||
Timestamp: d.Time,
|
||||
OpenInterest: d.OpenInterest,
|
||||
}
|
||||
}
|
||||
|
||||
func mapOpenInterestHistory(d []openInterestHistDTO, period string) []entity.OpenInterest {
|
||||
out := make([]entity.OpenInterest, 0, len(d))
|
||||
for _, x := range d {
|
||||
out = append(out, entity.OpenInterest{
|
||||
Source: sourceName,
|
||||
Symbol: x.Symbol,
|
||||
Period: period,
|
||||
Timestamp: x.Timestamp,
|
||||
OpenInterest: x.SumOpenInterest,
|
||||
OpenInterestValue: x.SumOpenInterestValue,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func mapLongShort(d []longShortRatioDTO, period, ratioType string) []entity.LongShortRatio {
|
||||
out := make([]entity.LongShortRatio, 0, len(d))
|
||||
for _, x := range d {
|
||||
longVal := x.LongAccount
|
||||
shortVal := x.ShortAccount
|
||||
if ratioType == entity.RatioTypeTopTraderPosition {
|
||||
longVal = x.LongPosition
|
||||
shortVal = x.ShortPosition
|
||||
}
|
||||
out = append(out, entity.LongShortRatio{
|
||||
Source: sourceName,
|
||||
Symbol: x.Symbol,
|
||||
Period: period,
|
||||
RatioType: ratioType,
|
||||
Timestamp: x.Timestamp,
|
||||
LongShortRatio: x.LongShortRatio,
|
||||
LongValue: longVal,
|
||||
ShortValue: shortVal,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func mapTakerVolume(d []takerVolumeDTO, symbol, period string) []entity.TakerBuySellVolume {
|
||||
out := make([]entity.TakerBuySellVolume, 0, len(d))
|
||||
for _, x := range d {
|
||||
out = append(out, entity.TakerBuySellVolume{
|
||||
Source: sourceName,
|
||||
Symbol: symbol,
|
||||
Period: period,
|
||||
Timestamp: x.Timestamp,
|
||||
BuySellRatio: x.BuySellRatio,
|
||||
BuyVolume: x.BuyVol,
|
||||
SellVolume: x.SellVol,
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
57
internal/repo/webapi/binance/market.go
Normal file
57
internal/repo/webapi/binance/market.go
Normal file
@@ -0,0 +1,57 @@
|
||||
package binance
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/url"
|
||||
"strconv"
|
||||
|
||||
"cryptoHermes/internal/entity"
|
||||
)
|
||||
|
||||
func (c *Client) GetKlines(ctx context.Context, symbol, interval string, limit int) ([]entity.Kline, error) {
|
||||
return c.GetKlinesRange(ctx, symbol, interval, 0, 0, limit)
|
||||
}
|
||||
|
||||
func (c *Client) GetKlinesRange(ctx context.Context, symbol, interval string, startMs, endMs int64, limit int) ([]entity.Kline, error) {
|
||||
if limit <= 0 {
|
||||
limit = 500
|
||||
}
|
||||
if limit > 1500 {
|
||||
limit = 1500
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
q.Set("interval", interval)
|
||||
q.Set("limit", strconv.Itoa(limit))
|
||||
if startMs > 0 {
|
||||
q.Set("startTime", strconv.FormatInt(startMs, 10))
|
||||
}
|
||||
if endMs > 0 {
|
||||
q.Set("endTime", strconv.FormatInt(endMs, 10))
|
||||
}
|
||||
|
||||
var raw [][]any
|
||||
if err := c.get(ctx, "/fapi/v1/klines", q, &raw); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
out := make([]entity.Kline, 0, len(raw))
|
||||
for _, row := range raw {
|
||||
k, err := parseKlineRow(symbol, interval, row)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, k)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (c *Client) GetTicker24h(ctx context.Context, symbol string) (*entity.Ticker24h, error) {
|
||||
q := url.Values{}
|
||||
q.Set("symbol", symbol)
|
||||
var dto tickerDTO
|
||||
if err := c.get(ctx, "/fapi/v1/ticker/24hr", q, &dto); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return mapTicker(&dto), nil
|
||||
}
|
||||
Reference in New Issue
Block a user