API 配额分级：免费累计 1000 次 + 公开注册自助领取更高配额密钥 #17
@@ -168,6 +168,7 @@ export const api = {
|
||||
owner_email?: string;
|
||||
tier?: string;
|
||||
rate_limit_per_min?: number;
|
||||
quota_total?: number;
|
||||
}) =>
|
||||
request<{ key: string; item: import("./types").ApiKey; warning: string }>(
|
||||
"/keys",
|
||||
|
||||
@@ -4,9 +4,10 @@ import type { ApiKey } from "../types";
|
||||
import { Copy, KeyRound, Plus, Trash2 } from "lucide-react";
|
||||
|
||||
const TIERS = [
|
||||
{ key: "free", label: "免费 (free)", rate: 120 },
|
||||
{ key: "partner", label: "合作方 (partner)", rate: 600 },
|
||||
{ key: "internal", label: "内部 (internal)", rate: 6000 },
|
||||
{ key: "free", label: "免费 (free)", rate: 120, quota: 1000 },
|
||||
{ key: "registered", label: "注册用户 (registered)", rate: 300, quota: 100000 },
|
||||
{ key: "partner", label: "合作方 (partner)", rate: 600, quota: 0 },
|
||||
{ key: "internal", label: "内部 (internal)", rate: 6000, quota: 0 },
|
||||
];
|
||||
|
||||
function tierLabel(tier: string): string {
|
||||
@@ -111,6 +112,7 @@ export default function ApiKeysPage() {
|
||||
<th className="px-4 py-2 font-medium">级别</th>
|
||||
<th className="px-4 py-2 font-medium">速率/分钟</th>
|
||||
<th className="px-4 py-2 font-medium">用量(今日/累计)</th>
|
||||
<th className="px-4 py-2 font-medium">累计配额</th>
|
||||
<th className="px-4 py-2 font-medium">状态</th>
|
||||
<th className="px-4 py-2 font-medium"></th>
|
||||
</tr>
|
||||
@@ -118,7 +120,7 @@ export default function ApiKeysPage() {
|
||||
<tbody className="divide-y">
|
||||
{rows.length === 0 ? (
|
||||
<tr>
|
||||
<td colSpan={7} className="px-4 py-8 text-center text-gray-400">
|
||||
<td colSpan={8} className="px-4 py-8 text-center text-gray-400">
|
||||
暂无密钥
|
||||
</td>
|
||||
</tr>
|
||||
@@ -139,6 +141,15 @@ export default function ApiKeysPage() {
|
||||
<td className="px-4 py-2 text-gray-600">
|
||||
{k.usage.today} / {k.usage.total}
|
||||
</td>
|
||||
<td className="px-4 py-2 text-gray-600">
|
||||
{k.quota_total > 0 ? (
|
||||
<span className={k.usage.total >= k.quota_total ? "text-red-600" : ""}>
|
||||
{k.usage.total.toLocaleString()} / {k.quota_total.toLocaleString()}
|
||||
</span>
|
||||
) : (
|
||||
<span className="text-gray-400">不限</span>
|
||||
)}
|
||||
</td>
|
||||
<td className="px-4 py-2">
|
||||
{k.revoked_at ? (
|
||||
<span className="text-xs rounded px-2 py-0.5 bg-red-50 text-red-700">
|
||||
@@ -182,13 +193,17 @@ function CreateKeyForm({
|
||||
const [ownerEmail, setOwnerEmail] = useState("");
|
||||
const [tier, setTier] = useState("free");
|
||||
const [rate, setRate] = useState(120);
|
||||
const [quota, setQuota] = useState(1000);
|
||||
const [busy, setBusy] = useState(false);
|
||||
const [error, setError] = useState("");
|
||||
|
||||
function pickTier(t: string) {
|
||||
setTier(t);
|
||||
const def = TIERS.find((x) => x.key === t);
|
||||
if (def) setRate(def.rate);
|
||||
if (def) {
|
||||
setRate(def.rate);
|
||||
setQuota(def.quota);
|
||||
}
|
||||
}
|
||||
|
||||
async function submit() {
|
||||
@@ -204,6 +219,7 @@ function CreateKeyForm({
|
||||
owner_email: ownerEmail.trim() || undefined,
|
||||
tier,
|
||||
rate_limit_per_min: rate,
|
||||
quota_total: quota,
|
||||
});
|
||||
onCreated(res.key);
|
||||
} catch (e) {
|
||||
@@ -260,6 +276,16 @@ function CreateKeyForm({
|
||||
onChange={(e) => setRate(Math.max(1, parseInt(e.target.value || "1", 10)))}
|
||||
/>
|
||||
</label>
|
||||
<label className="block">
|
||||
<span className="text-xs text-gray-500">累计配额（总调用次数，0=不限）</span>
|
||||
<input
|
||||
type="number"
|
||||
min={0}
|
||||
className="w-full border rounded-md px-3 py-2 text-sm mt-1"
|
||||
value={quota}
|
||||
onChange={(e) => setQuota(Math.max(0, parseInt(e.target.value || "0", 10)))}
|
||||
/>
|
||||
</label>
|
||||
</div>
|
||||
<div className="mt-4 flex gap-2">
|
||||
<button
|
||||
|
||||
@@ -199,6 +199,7 @@ export interface ApiKey {
|
||||
owner_email: string | null;
|
||||
tier: string;
|
||||
rate_limit_per_min: number;
|
||||
quota_total: number;
|
||||
revoked_at: string | null;
|
||||
created_by: string | null;
|
||||
created_at: string;
|
||||
|
||||
@@ -37,7 +37,8 @@ func main() {
|
||||
log.Print("warning: Redis not configured; public API rate limiting disabled")
|
||||
}
|
||||
h := handler.New(store.New(pool), publicweb.Dist()).
|
||||
WithRateLimit(limiter, cfg.AnonRateLimitPerMin)
|
||||
WithRateLimit(limiter, cfg.AnonRateLimitPerMin).
|
||||
WithQuotas(cfg.AnonTotalQuota, cfg.RegisteredRateLimitPerMin, cfg.RegisteredQuotaTotal)
|
||||
|
||||
srv := &http.Server{
|
||||
Addr: cfg.Addr,
|
||||
|
||||
@@ -46,7 +46,7 @@ func (h *Handler) CreateAPIKey(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusBadRequest, "bad_request", "名称不能为空")
|
||||
return
|
||||
}
|
||||
if in.Tier != "" && in.Tier != "free" && in.Tier != "partner" && in.Tier != "internal" {
|
||||
if in.Tier != "" && in.Tier != "free" && in.Tier != "registered" && in.Tier != "partner" && in.Tier != "internal" {
|
||||
writeError(w, http.StatusBadRequest, "bad_request", "tier 取值无效")
|
||||
return
|
||||
}
|
||||
|
||||
@@ -19,6 +19,7 @@ type APIKeyRow struct {
|
||||
OwnerEmail *string `json:"owner_email"`
|
||||
Tier string `json:"tier"`
|
||||
RateLimitPerMin int `json:"rate_limit_per_min"`
|
||||
QuotaTotal int64 `json:"quota_total"`
|
||||
RevokedAt *string `json:"revoked_at"`
|
||||
CreatedBy *string `json:"created_by"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
@@ -30,6 +31,7 @@ type APIKeyInput struct {
|
||||
OwnerEmail string `json:"owner_email"`
|
||||
Tier string `json:"tier"`
|
||||
RateLimitPerMin int `json:"rate_limit_per_min"`
|
||||
QuotaTotal int64 `json:"quota_total"`
|
||||
}
|
||||
|
||||
// CreateAPIKey issues a new key, returning the one-time plaintext alongside the
|
||||
@@ -43,6 +45,10 @@ func (s *Store) CreateAPIKey(ctx context.Context, in APIKeyInput, createdBy stri
|
||||
if rate <= 0 {
|
||||
rate = 120
|
||||
}
|
||||
quota := in.QuotaTotal
|
||||
if quota < 0 {
|
||||
quota = 0
|
||||
}
|
||||
var owner *string
|
||||
if e := strings.TrimSpace(in.OwnerEmail); e != "" {
|
||||
owner = &e
|
||||
@@ -56,12 +62,12 @@ func (s *Store) CreateAPIKey(ctx context.Context, in APIKeyInput, createdBy stri
|
||||
var revoked, created *time.Time
|
||||
var createdByOut *string
|
||||
err = s.pool.QueryRow(ctx, `
|
||||
INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, created_by)
|
||||
VALUES ($1, $2, $3, $4, $5, $6, $7)
|
||||
RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at`,
|
||||
strings.TrimSpace(in.Name), prefix, hash, owner, tier, rate, createdBy,
|
||||
INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
|
||||
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
|
||||
RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, quota_total, revoked_at, created_by, created_at`,
|
||||
strings.TrimSpace(in.Name), prefix, hash, owner, tier, rate, quota, createdBy,
|
||||
).Scan(&row.ID, &row.Name, &row.KeyPrefix, &row.OwnerEmail, &row.Tier,
|
||||
&row.RateLimitPerMin, &revoked, &createdByOut, &created)
|
||||
&row.RateLimitPerMin, &row.QuotaTotal, &revoked, &createdByOut, &created)
|
||||
if err != nil {
|
||||
return "", row, err
|
||||
}
|
||||
@@ -75,7 +81,7 @@ RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_a
|
||||
// ListAPIKeys returns all keys (active first, newest first).
|
||||
func (s *Store) ListAPIKeys(ctx context.Context) ([]APIKeyRow, error) {
|
||||
rows, err := s.pool.Query(ctx, `
|
||||
SELECT id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at
|
||||
SELECT id, name, key_prefix, owner_email, tier, rate_limit_per_min, quota_total, revoked_at, created_by, created_at
|
||||
FROM api_key
|
||||
ORDER BY (revoked_at IS NULL) DESC, created_at DESC`)
|
||||
if err != nil {
|
||||
@@ -87,7 +93,7 @@ ORDER BY (revoked_at IS NULL) DESC, created_at DESC`)
|
||||
var r APIKeyRow
|
||||
var revoked, created *time.Time
|
||||
if err := rows.Scan(&r.ID, &r.Name, &r.KeyPrefix, &r.OwnerEmail, &r.Tier,
|
||||
&r.RateLimitPerMin, &revoked, &r.CreatedBy, &created); err != nil {
|
||||
&r.RateLimitPerMin, &r.QuotaTotal, &revoked, &r.CreatedBy, &created); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if revoked != nil {
|
||||
|
||||
@@ -9,19 +9,25 @@ import (
|
||||
// Values are read from environment variables with sensible defaults so the
|
||||
// server can boot in a local Docker Compose setup without extra configuration.
|
||||
type Config struct {
|
||||
Addr string
|
||||
DatabaseURL string
|
||||
RedisURL string
|
||||
AnonRateLimitPerMin int
|
||||
Addr string
|
||||
DatabaseURL string
|
||||
RedisURL string
|
||||
AnonRateLimitPerMin int
|
||||
AnonTotalQuota int
|
||||
RegisteredRateLimitPerMin int
|
||||
RegisteredQuotaTotal int
|
||||
}
|
||||
|
||||
// Load reads configuration from the environment.
|
||||
func Load() Config {
|
||||
return Config{
|
||||
Addr: getenv("OPENGOODS_ADDR", ":8080"),
|
||||
DatabaseURL: getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
|
||||
RedisURL: getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
|
||||
AnonRateLimitPerMin: getenvInt("OPENGOODS_ANON_RATE_LIMIT_PER_MIN", 60),
|
||||
Addr: getenv("OPENGOODS_ADDR", ":8080"),
|
||||
DatabaseURL: getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
|
||||
RedisURL: getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
|
||||
AnonRateLimitPerMin: getenvInt("OPENGOODS_ANON_RATE_LIMIT_PER_MIN", 60),
|
||||
AnonTotalQuota: getenvInt("OPENGOODS_ANON_TOTAL_QUOTA", 1000),
|
||||
RegisteredRateLimitPerMin: getenvInt("OPENGOODS_REGISTERED_RATE_LIMIT_PER_MIN", 300),
|
||||
RegisteredQuotaTotal: getenvInt("OPENGOODS_REGISTERED_QUOTA_TOTAL", 100000),
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
package handler
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"net/http"
|
||||
"regexp"
|
||||
"strings"
|
||||
|
||||
"github.com/baicai2026-baicai/goods/api/internal/store"
|
||||
)
|
||||
|
||||
// emailRe is a deliberately permissive sanity check; real validation is the
|
||||
// unique constraint plus the user being able to receive their own key.
|
||||
var emailRe = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[^@\s]+$`)
|
||||
|
||||
const minPasswordLen = 8
|
||||
|
||||
type credentials struct {
|
||||
Email string `json:"email"`
|
||||
Password string `json:"password"`
|
||||
}
|
||||
|
||||
func decodeCredentials(w http.ResponseWriter, r *http.Request) (credentials, bool) {
|
||||
var c credentials
|
||||
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&c); err != nil {
|
||||
writeError(w, r, http.StatusBadRequest, "invalid_body", "请求格式无效")
|
||||
return credentials{}, false
|
||||
}
|
||||
c.Email = strings.TrimSpace(c.Email)
|
||||
if !emailRe.MatchString(c.Email) {
|
||||
writeError(w, r, http.StatusBadRequest, "invalid_email", "邮箱格式无效")
|
||||
return credentials{}, false
|
||||
}
|
||||
if len(c.Password) < minPasswordLen {
|
||||
writeError(w, r, http.StatusBadRequest, "weak_password", "密码至少需要 8 位")
|
||||
return credentials{}, false
|
||||
}
|
||||
return c, true
|
||||
}
|
||||
|
||||
// keyResponse is returned whenever a fresh plaintext key is issued; the key is
|
||||
// shown exactly once and cannot be recovered afterwards.
|
||||
type keyResponse struct {
|
||||
Email string `json:"email"`
|
||||
APIKey string `json:"api_key"`
|
||||
KeyPrefix string `json:"key_prefix"`
|
||||
RateLimitPerMin int `json:"rate_limit_per_min"`
|
||||
QuotaTotal int64 `json:"quota_total"`
|
||||
}
|
||||
|
||||
// Register creates an account and issues its first API key. POST {email, password}.
|
||||
func (h *Handler) Register(w http.ResponseWriter, r *http.Request) {
|
||||
c, ok := decodeCredentials(w, r)
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
key, acct, err := h.store.RegisterUser(r.Context(), c.Email, c.Password, h.regRatePerMin, h.regQuotaTotal)
|
||||
if errors.Is(err, store.ErrEmailTaken) {
|
||||
writeError(w, r, http.StatusConflict, "email_taken", "该邮箱已注册，请直接登录查看或重置密钥")
|
||||
return
|
||||
}
|
||||
if h.handleErr(w, r, err) {
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusCreated, keyResponse{
|
||||
Email: acct.Email,
|
||||
APIKey: key,
|
||||
KeyPrefix: acct.KeyPrefix,
|
||||
RateLimitPerMin: acct.RateLimitPerMin,
|
||||
QuotaTotal: acct.QuotaTotal,
|
||||
})
|
||||
}
|
||||
|
||||
// AccountInfo verifies credentials and returns the account's key metadata plus
|
||||
// cumulative usage. POST {email, password}. The plaintext key is not returned.
|
||||
func (h *Handler) AccountInfo(w http.ResponseWriter, r *http.Request) {
|
||||
c, ok := decodeCredentials(w, r)
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
acct, err := h.store.Authenticate(r.Context(), c.Email, c.Password)
|
||||
if errors.Is(err, store.ErrNotFound) {
|
||||
writeError(w, r, http.StatusUnauthorized, "invalid_credentials", "邮箱或密码错误")
|
||||
return
|
||||
}
|
||||
if h.handleErr(w, r, err) {
|
||||
return
|
||||
}
|
||||
used := h.limiter.TotalUsed(r.Context(), acct.KeyID)
|
||||
remaining := acct.QuotaTotal - used
|
||||
if remaining < 0 {
|
||||
remaining = 0
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]any{
|
||||
"email": acct.Email,
|
||||
"key_prefix": acct.KeyPrefix,
|
||||
"rate_limit_per_min": acct.RateLimitPerMin,
|
||||
"quota_total": acct.QuotaTotal,
|
||||
"quota_used": used,
|
||||
"quota_remaining": remaining,
|
||||
})
|
||||
}
|
||||
|
||||
// RegenerateKey revokes the account's current key and issues a new one, carrying
|
||||
// over cumulative usage so the quota cannot be reset. POST {email, password}.
|
||||
func (h *Handler) RegenerateKey(w http.ResponseWriter, r *http.Request) {
|
||||
c, ok := decodeCredentials(w, r)
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
key, acct, oldKeyID, err := h.store.RegenerateKey(r.Context(), c.Email, c.Password, h.regRatePerMin, h.regQuotaTotal)
|
||||
if errors.Is(err, store.ErrNotFound) {
|
||||
writeError(w, r, http.StatusUnauthorized, "invalid_credentials", "邮箱或密码错误")
|
||||
return
|
||||
}
|
||||
if h.handleErr(w, r, err) {
|
||||
return
|
||||
}
|
||||
h.limiter.CopyTotal(r.Context(), oldKeyID, acct.KeyID)
|
||||
writeJSON(w, http.StatusOK, keyResponse{
|
||||
Email: acct.Email,
|
||||
APIKey: key,
|
||||
KeyPrefix: acct.KeyPrefix,
|
||||
RateLimitPerMin: acct.RateLimitPerMin,
|
||||
QuotaTotal: acct.QuotaTotal,
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,149 @@
|
||||
package handler
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/jackc/pgx/v5/pgxpool"
|
||||
"github.com/redis/go-redis/v9"
|
||||
|
||||
"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
|
||||
"github.com/baicai2026-baicai/goods/api/internal/store"
|
||||
)
|
||||
|
||||
func cleanupCounter(t *testing.T, subject string) {
|
||||
t.Helper()
|
||||
redisURL := os.Getenv("OPENGOODS_REDIS_URL")
|
||||
if redisURL == "" {
|
||||
redisURL = "redis://localhost:6379/0"
|
||||
}
|
||||
opt, err := redis.ParseURL(redisURL)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
rdb := redis.NewClient(opt)
|
||||
defer rdb.Close()
|
||||
rdb.Del(context.Background(), "usage:total:"+subject)
|
||||
}
|
||||
|
||||
// newQuotaHandler builds a handler backed by the test DB and a live Redis
|
||||
// limiter, with a small anonymous quota so exhaustion is cheap to exercise.
|
||||
func newQuotaHandler(t *testing.T, anonQuota int) *Handler {
|
||||
t.Helper()
|
||||
dsn := os.Getenv("OPENGOODS_DATABASE_URL")
|
||||
if dsn == "" {
|
||||
dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
|
||||
defer cancel()
|
||||
pool, err := pgxpool.New(ctx, dsn)
|
||||
if err != nil {
|
||||
t.Skipf("no database: %v", err)
|
||||
}
|
||||
if err := pool.Ping(ctx); err != nil {
|
||||
pool.Close()
|
||||
t.Skipf("database not reachable: %v", err)
|
||||
}
|
||||
var hasUser bool
|
||||
if err := pool.QueryRow(ctx, "SELECT to_regclass('public.app_user') IS NOT NULL").Scan(&hasUser); err != nil || !hasUser {
|
||||
pool.Close()
|
||||
t.Skip("migrations not applied")
|
||||
}
|
||||
redisURL := os.Getenv("OPENGOODS_REDIS_URL")
|
||||
if redisURL == "" {
|
||||
redisURL = "redis://localhost:6379/0"
|
||||
}
|
||||
limiter := ratelimit.New(redisURL)
|
||||
pingCtx, pingCancel := context.WithTimeout(context.Background(), time.Second)
|
||||
defer pingCancel()
|
||||
if err := limiter.Ping(pingCtx); err != nil {
|
||||
pool.Close()
|
||||
t.Skipf("redis not reachable: %v", err)
|
||||
}
|
||||
t.Cleanup(pool.Close)
|
||||
return New(store.New(pool), nil).
|
||||
WithRateLimit(limiter, 1000).
|
||||
WithQuotas(anonQuota, 300, 100000)
|
||||
}
|
||||
|
||||
func cleanupAccount(t *testing.T, email string) {
|
||||
t.Helper()
|
||||
dsn := os.Getenv("OPENGOODS_DATABASE_URL")
|
||||
if dsn == "" {
|
||||
dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
|
||||
}
|
||||
ctx := context.Background()
|
||||
pool, err := pgxpool.New(ctx, dsn)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
defer pool.Close()
|
||||
_, _ = pool.Exec(ctx, "DELETE FROM app_user WHERE lower(email)=lower($1)", email)
|
||||
_, _ = pool.Exec(ctx, "DELETE FROM api_key WHERE owner_email=$1", email)
|
||||
}
|
||||
|
||||
func TestAnonTotalQuotaExhausts(t *testing.T) {
|
||||
h := newQuotaHandler(t, 3)
|
||||
// Unique client IP so the lifetime counter starts fresh for this test; the
|
||||
// counter never expires, so drop it afterwards to keep runs independent.
|
||||
n := time.Now().UnixNano()
|
||||
ip := fmt.Sprintf("203.%d.%d.%d", n/65536%256, n/256%256, n%256)
|
||||
t.Cleanup(func() { cleanupCounter(t, "ip:"+ip) })
|
||||
call := func() *httptest.ResponseRecorder {
|
||||
req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/stats", nil)
|
||||
req.RemoteAddr = ip + ":12345"
|
||||
rec := httptest.NewRecorder()
|
||||
h.Router().ServeHTTP(rec, req)
|
||||
return rec
|
||||
}
|
||||
for i := 1; i <= 3; i++ {
|
||||
if rec := call(); rec.Code != http.StatusOK {
|
||||
t.Fatalf("call %d should be allowed, got %d (%s)", i, rec.Code, rec.Body.String())
|
||||
}
|
||||
}
|
||||
rec := call()
|
||||
if rec.Code != http.StatusForbidden {
|
||||
t.Fatalf("4th call should be 403 quota_exhausted, got %d (%s)", rec.Code, rec.Body.String())
|
||||
}
|
||||
if !strings.Contains(rec.Body.String(), "quota_exhausted") {
|
||||
t.Fatalf("expected quota_exhausted error, got %s", rec.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterIssuesHigherQuotaKey(t *testing.T) {
|
||||
h := newQuotaHandler(t, 1000)
|
||||
email := fmt.Sprintf("h-user-%d@example.com", time.Now().UnixNano())
|
||||
t.Cleanup(func() { cleanupAccount(t, email) })
|
||||
|
||||
body := fmt.Sprintf(`{"email":%q,"password":"supersecret"}`, email)
|
||||
req := httptest.NewRequest(http.MethodPost, "/api/"+APIVersion+"/register", strings.NewReader(body))
|
||||
req.RemoteAddr = "198.51.100.7:9999"
|
||||
rec := httptest.NewRecorder()
|
||||
h.Router().ServeHTTP(rec, req)
|
||||
if rec.Code != http.StatusCreated {
|
||||
t.Fatalf("register status = %d (%s)", rec.Code, rec.Body.String())
|
||||
}
|
||||
var resp keyResponse
|
||||
if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if resp.APIKey == "" || resp.QuotaTotal != 100000 || resp.RateLimitPerMin != 300 {
|
||||
t.Fatalf("unexpected register response: %+v", resp)
|
||||
}
|
||||
|
||||
// A second registration with the same email conflicts.
|
||||
req2 := httptest.NewRequest(http.MethodPost, "/api/"+APIVersion+"/register", strings.NewReader(body))
|
||||
req2.RemoteAddr = "198.51.100.7:9999"
|
||||
rec2 := httptest.NewRecorder()
|
||||
h.Router().ServeHTTP(rec2, req2)
|
||||
if rec2.Code != http.StatusConflict {
|
||||
t.Fatalf("duplicate register status = %d (%s)", rec2.Code, rec2.Body.String())
|
||||
}
|
||||
}
|
||||
@@ -37,20 +37,43 @@ const (
|
||||
// defaultAnonLimit is the per-minute request budget for unauthenticated
|
||||
// callers (identified by client IP) when none is configured.
|
||||
defaultAnonLimit = 60
|
||||
|
||||
// defaultAnonTotalQuota is the lifetime number of calls an anonymous caller
|
||||
// (by IP) may make before being asked to register for a higher quota.
|
||||
defaultAnonTotalQuota = 1000
|
||||
|
||||
// defaultRegRatePerMin / defaultRegQuotaTotal are the per-minute budget and
|
||||
// cumulative quota granted to a self-registered API key.
|
||||
defaultRegRatePerMin = 300
|
||||
defaultRegQuotaTotal = 100000
|
||||
|
||||
// registerRatePerMin caps account registration/login attempts per IP to
|
||||
// curb abuse; these endpoints sit outside the metered quota group.
|
||||
registerRatePerMin = 10
|
||||
)
|
||||
|
||||
// Handler holds dependencies shared by the HTTP routes.
|
||||
type Handler struct {
|
||||
store *store.Store
|
||||
spa fs.FS
|
||||
limiter *ratelimit.Limiter
|
||||
anonLimit int
|
||||
store *store.Store
|
||||
spa fs.FS
|
||||
limiter *ratelimit.Limiter
|
||||
anonLimit int
|
||||
anonTotalQuota int64
|
||||
regRatePerMin int
|
||||
regQuotaTotal int64
|
||||
}
|
||||
|
||||
// New constructs a Handler backed by the given store. spa may be nil (JSON-only).
|
||||
// Rate limiting is disabled until WithRateLimit is called.
|
||||
func New(s *store.Store, spa fs.FS) *Handler {
|
||||
return &Handler{store: s, spa: spa, anonLimit: defaultAnonLimit}
|
||||
return &Handler{
|
||||
store: s,
|
||||
spa: spa,
|
||||
anonLimit: defaultAnonLimit,
|
||||
anonTotalQuota: defaultAnonTotalQuota,
|
||||
regRatePerMin: defaultRegRatePerMin,
|
||||
regQuotaTotal: defaultRegQuotaTotal,
|
||||
}
|
||||
}
|
||||
|
||||
// WithRateLimit attaches a Redis-backed limiter and the anonymous per-minute
|
||||
@@ -64,6 +87,22 @@ func (h *Handler) WithRateLimit(l *ratelimit.Limiter, anonPerMin int) *Handler {
|
||||
return h
|
||||
}
|
||||
|
||||
// WithQuotas configures the cumulative free quota for anonymous callers and the
|
||||
// per-minute rate + cumulative quota self-registered keys receive. Non-positive
|
||||
// values keep the defaults.
|
||||
func (h *Handler) WithQuotas(anonTotal, regPerMin, regTotal int) *Handler {
|
||||
if anonTotal > 0 {
|
||||
h.anonTotalQuota = int64(anonTotal)
|
||||
}
|
||||
if regPerMin > 0 {
|
||||
h.regRatePerMin = regPerMin
|
||||
}
|
||||
if regTotal > 0 {
|
||||
h.regQuotaTotal = int64(regTotal)
|
||||
}
|
||||
return h
|
||||
}
|
||||
|
||||
// Router builds the top-level HTTP handler with middleware and routes mounted.
|
||||
func (h *Handler) Router() http.Handler {
|
||||
r := chi.NewRouter()
|
||||
@@ -91,6 +130,16 @@ func (h *Handler) Router() http.Handler {
|
||||
r.Get("/sources/{id}", h.SourceByID)
|
||||
r.Get("/stats", h.Stats)
|
||||
})
|
||||
|
||||
// Self-service account routes. Lightly IP-throttled to curb abuse but
|
||||
// outside the metered quota group so a user can always register or
|
||||
// check their key even after exhausting the free anonymous quota.
|
||||
r.Group(func(r chi.Router) {
|
||||
r.Use(h.registerLimit)
|
||||
r.Post("/register", h.Register)
|
||||
r.Post("/account", h.AccountInfo)
|
||||
r.Post("/account/regenerate", h.RegenerateKey)
|
||||
})
|
||||
})
|
||||
|
||||
// Public SPA (homepage + search + contribute). API routes above take
|
||||
|
||||
@@ -24,8 +24,11 @@ const apiKeyIDKey ctxKey = 0
|
||||
// are set on every response; over-budget callers get 429 + Retry-After.
|
||||
func (h *Handler) rateLimit(next http.Handler) http.Handler {
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
id := "ip:" + clientIP(r)
|
||||
ip := clientIP(r)
|
||||
id := "ip:" + ip
|
||||
subject := "ip:" + ip // cumulative-quota counter subject
|
||||
limit := h.anonLimit
|
||||
quota := h.anonTotalQuota
|
||||
keyID := ""
|
||||
|
||||
if raw := presentedKey(r); raw != "" {
|
||||
@@ -45,6 +48,8 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
|
||||
keyID = k.ID
|
||||
limit = k.RateLimitPerMin
|
||||
id = "key:" + k.ID
|
||||
subject = k.ID
|
||||
quota = k.QuotaTotal
|
||||
}
|
||||
|
||||
res := h.limiter.Allow(r.Context(), id, limit, time.Minute)
|
||||
@@ -61,8 +66,36 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
|
||||
return
|
||||
}
|
||||
|
||||
// Attribute one call to the caller's lifetime counter, then enforce the
|
||||
// cumulative quota (quota <= 0 means unlimited). Keys also get daily and
|
||||
// last-used stats recorded for the admin console.
|
||||
var used int64
|
||||
if keyID != "" {
|
||||
h.limiter.RecordUsage(r.Context(), keyID)
|
||||
used = h.limiter.TotalUsed(r.Context(), keyID)
|
||||
} else {
|
||||
used = h.limiter.IncrTotal(r.Context(), subject)
|
||||
}
|
||||
if quota > 0 {
|
||||
remaining := quota - used
|
||||
if remaining < 0 {
|
||||
remaining = 0
|
||||
}
|
||||
w.Header().Set("X-Quota-Limit", strconv.FormatInt(quota, 10))
|
||||
w.Header().Set("X-Quota-Used", strconv.FormatInt(used, 10))
|
||||
w.Header().Set("X-Quota-Remaining", strconv.FormatInt(remaining, 10))
|
||||
if used > quota {
|
||||
if keyID == "" {
|
||||
writeError(w, r, http.StatusForbidden, "quota_exhausted",
|
||||
"免费额度（共 "+strconv.FormatInt(quota, 10)+" 次）已用尽，请注册账号获取更高配额的 API 密钥")
|
||||
} else {
|
||||
writeError(w, r, http.StatusForbidden, "quota_exhausted", "API 密钥配额已用尽")
|
||||
}
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
if keyID != "" {
|
||||
next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), apiKeyIDKey, keyID)))
|
||||
return
|
||||
}
|
||||
@@ -70,6 +103,25 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
|
||||
})
|
||||
}
|
||||
|
||||
// registerLimit throttles self-service account endpoints per client IP without
|
||||
// consuming the metered free quota, so a caller can still register or recover
|
||||
// their key after exhausting the anonymous quota.
|
||||
func (h *Handler) registerLimit(next http.Handler) http.Handler {
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
res := h.limiter.Allow(r.Context(), "register:"+clientIP(r), h.regRatePerMin, time.Minute)
|
||||
if !res.Allowed {
|
||||
retry := res.ResetUnix - time.Now().Unix()
|
||||
if retry < 1 {
|
||||
retry = 1
|
||||
}
|
||||
w.Header().Set("Retry-After", strconv.FormatInt(retry, 10))
|
||||
writeError(w, r, http.StatusTooManyRequests, "rate_limited", "操作过于频繁，请稍后再试")
|
||||
return
|
||||
}
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
|
||||
// presentedKey extracts an API key from the X-API-Key header or a Bearer token.
|
||||
func presentedKey(r *http.Request) string {
|
||||
if v := strings.TrimSpace(r.Header.Get("X-API-Key")); v != "" {
|
||||
|
||||
@@ -10,7 +10,8 @@
|
||||
"tags": [
|
||||
{ "name": "products" },
|
||||
{ "name": "catalog" },
|
||||
{ "name": "meta" }
|
||||
{ "name": "meta" },
|
||||
{ "name": "account" }
|
||||
],
|
||||
"security": [{ "ApiKeyHeader": [] }, { "BearerKey": [] }, {}],
|
||||
"paths": {
|
||||
@@ -114,6 +115,35 @@
|
||||
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
||||
"responses": { "200": { "description": "Source" }, "404": { "$ref": "#/components/responses/NotFound" } }
|
||||
}
|
||||
},
|
||||
"/register": {
|
||||
"post": {
|
||||
"tags": ["account"],
|
||||
"summary": "Register an account and issue an API key",
|
||||
"description": "Self-service registration; returns the plaintext API key exactly once.",
|
||||
"security": [],
|
||||
"requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } } } } } },
|
||||
"responses": { "201": { "description": "Account created; plaintext key returned once" }, "400": { "description": "Invalid email or weak password" }, "409": { "description": "Email already registered" } }
|
||||
}
|
||||
},
|
||||
"/account": {
|
||||
"post": {
|
||||
"tags": ["account"],
|
||||
"summary": "View account key metadata and cumulative quota usage",
|
||||
"security": [],
|
||||
"requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } },
|
||||
"responses": { "200": { "description": "Account info with quota usage" }, "401": { "description": "Invalid credentials" } }
|
||||
}
|
||||
},
|
||||
"/account/regenerate": {
|
||||
"post": {
|
||||
"tags": ["account"],
|
||||
"summary": "Revoke the current key and issue a new one",
|
||||
"description": "Cumulative usage carries over; returns the plaintext key exactly once.",
|
||||
"security": [],
|
||||
"requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } },
|
||||
"responses": { "200": { "description": "New plaintext key returned once" }, "401": { "description": "Invalid credentials" } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
|
||||
@@ -116,6 +116,45 @@ func (l *Limiter) RecordUsage(ctx context.Context, keyID string) {
|
||||
_, _ = pipe.Exec(ctx)
|
||||
}
|
||||
|
||||
// IncrTotal increments the lifetime call counter for subject and returns the
|
||||
// new total. The counter never expires; it is the cumulative number of calls
|
||||
// attributed to a caller (an API key id, or "ip:<addr>" for anonymous callers).
|
||||
// Fails open returning 0 on any error so quota enforcement never takes the API
|
||||
// down.
|
||||
func (l *Limiter) IncrTotal(ctx context.Context, subject string) int64 {
|
||||
if !l.Enabled() || subject == "" {
|
||||
return 0
|
||||
}
|
||||
n, err := l.rdb.Incr(ctx, "usage:total:"+subject).Result()
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
return n
|
||||
}
|
||||
|
||||
// CopyTotal carries a lifetime counter from one subject to another, used when a
|
||||
// key is regenerated so a caller cannot reset their cumulative quota. Best
|
||||
// effort: a missing or zero source counter is a no-op.
|
||||
func (l *Limiter) CopyTotal(ctx context.Context, from, to string) {
|
||||
if !l.Enabled() || from == "" || to == "" {
|
||||
return
|
||||
}
|
||||
n, err := l.rdb.Get(ctx, "usage:total:"+from).Int64()
|
||||
if err != nil || n == 0 {
|
||||
return
|
||||
}
|
||||
l.rdb.Set(ctx, "usage:total:"+to, n, 0)
|
||||
}
|
||||
|
||||
// TotalUsed reads the lifetime call counter for subject without incrementing.
|
||||
func (l *Limiter) TotalUsed(ctx context.Context, subject string) int64 {
|
||||
if !l.Enabled() || subject == "" {
|
||||
return 0
|
||||
}
|
||||
n, _ := l.rdb.Get(ctx, "usage:total:"+subject).Int64()
|
||||
return n
|
||||
}
|
||||
|
||||
// Usage reads aggregated usage for a key. Returns a zero-value stat on error.
|
||||
func (l *Limiter) Usage(ctx context.Context, keyID string) UsageStat {
|
||||
var st UsageStat
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
package store
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"strings"
|
||||
|
||||
"github.com/jackc/pgx/v5"
|
||||
"github.com/jackc/pgx/v5/pgconn"
|
||||
"golang.org/x/crypto/bcrypt"
|
||||
|
||||
"github.com/baicai2026-baicai/goods/api/internal/apikey"
|
||||
)
|
||||
|
||||
// ErrEmailTaken is returned when registering an email that already exists.
|
||||
var ErrEmailTaken = errors.New("email already registered")
|
||||
|
||||
// Account is a self-registered public-API user and its current key metadata.
|
||||
type Account struct {
|
||||
ID string `json:"id"`
|
||||
Email string `json:"email"`
|
||||
KeyID string `json:"-"`
|
||||
KeyPrefix string `json:"key_prefix"`
|
||||
RateLimitPerMin int `json:"rate_limit_per_min"`
|
||||
QuotaTotal int64 `json:"quota_total"`
|
||||
}
|
||||
|
||||
// bcryptDummyHash is compared against on unknown-email logins to keep timing
|
||||
// roughly constant and avoid leaking which emails are registered.
|
||||
const bcryptDummyHash = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
|
||||
|
||||
func isUniqueViolation(err error) bool {
|
||||
var pgErr *pgconn.PgError
|
||||
return errors.As(err, &pgErr) && pgErr.Code == "23505"
|
||||
}
|
||||
|
||||
// RegisterUser creates an account plus a self-issued API key with the given
|
||||
// per-minute rate and cumulative quota, returning the plaintext key (shown
|
||||
// once). Email uniqueness is case-insensitive; ErrEmailTaken signals a dupe.
|
||||
func (s *Store) RegisterUser(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, err error) {
|
||||
email = strings.TrimSpace(email)
|
||||
pwHash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
|
||||
if err != nil {
|
||||
return "", Account{}, err
|
||||
}
|
||||
key, keyHash, prefix, err := apikey.Generate()
|
||||
if err != nil {
|
||||
return "", Account{}, err
|
||||
}
|
||||
|
||||
tx, err := s.pool.Begin(ctx)
|
||||
if err != nil {
|
||||
return "", Account{}, err
|
||||
}
|
||||
defer func() { _ = tx.Rollback(ctx) }()
|
||||
|
||||
var keyID string
|
||||
if err = tx.QueryRow(ctx,
|
||||
`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
|
||||
VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
|
||||
"user:"+strings.ToLower(email), prefix, keyHash, email, ratePerMin, quotaTotal,
|
||||
).Scan(&keyID); err != nil {
|
||||
return "", Account{}, err
|
||||
}
|
||||
|
||||
var userID string
|
||||
if err = tx.QueryRow(ctx,
|
||||
`INSERT INTO app_user (email, password_hash, api_key_id) VALUES ($1,$2,$3) RETURNING id`,
|
||||
email, string(pwHash), keyID,
|
||||
).Scan(&userID); err != nil {
|
||||
if isUniqueViolation(err) {
|
||||
return "", Account{}, ErrEmailTaken
|
||||
}
|
||||
return "", Account{}, err
|
||||
}
|
||||
|
||||
if err = tx.Commit(ctx); err != nil {
|
||||
return "", Account{}, err
|
||||
}
|
||||
return key, Account{
|
||||
ID: userID, Email: email, KeyID: keyID, KeyPrefix: prefix,
|
||||
RateLimitPerMin: ratePerMin, QuotaTotal: quotaTotal,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Authenticate verifies an email/password pair and returns the account with its
|
||||
// current (non-revoked) key metadata. Returns ErrNotFound on unknown email or
|
||||
// wrong password.
|
||||
func (s *Store) Authenticate(ctx context.Context, email, password string) (Account, error) {
|
||||
email = strings.TrimSpace(email)
|
||||
var (
|
||||
userID, pwHash string
|
||||
keyID *string
|
||||
)
|
||||
err := s.pool.QueryRow(ctx,
|
||||
`SELECT id, password_hash, api_key_id FROM app_user WHERE lower(email) = lower($1)`, email,
|
||||
).Scan(&userID, &pwHash, &keyID)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
_ = bcrypt.CompareHashAndPassword([]byte(bcryptDummyHash), []byte(password))
|
||||
return Account{}, ErrNotFound
|
||||
}
|
||||
if err != nil {
|
||||
return Account{}, err
|
||||
}
|
||||
if err := bcrypt.CompareHashAndPassword([]byte(pwHash), []byte(password)); err != nil {
|
||||
return Account{}, ErrNotFound
|
||||
}
|
||||
|
||||
acct := Account{ID: userID, Email: email}
|
||||
if keyID != nil {
|
||||
acct.KeyID = *keyID
|
||||
_ = s.pool.QueryRow(ctx,
|
||||
`SELECT key_prefix, rate_limit_per_min, quota_total
|
||||
FROM api_key WHERE id = $1 AND revoked_at IS NULL`, *keyID,
|
||||
).Scan(&acct.KeyPrefix, &acct.RateLimitPerMin, &acct.QuotaTotal)
|
||||
}
|
||||
return acct, nil
|
||||
}
|
||||
|
||||
// RegenerateKey verifies credentials, revokes the account's current key, and
|
||||
// issues a fresh one with the same rate/quota, returning the plaintext key and
|
||||
// the previous key id (so cumulative usage can be carried over). Returns
|
||||
// ErrNotFound on bad credentials.
|
||||
func (s *Store) RegenerateKey(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, oldKeyID string, err error) {
|
||||
cur, err := s.Authenticate(ctx, email, password)
|
||||
if err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
key, keyHash, prefix, err := apikey.Generate()
|
||||
if err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
|
||||
oldKeyID = cur.KeyID
|
||||
|
||||
tx, err := s.pool.Begin(ctx)
|
||||
if err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
defer func() { _ = tx.Rollback(ctx) }()
|
||||
|
||||
if oldKeyID != "" {
|
||||
if _, err = tx.Exec(ctx,
|
||||
`UPDATE api_key SET revoked_at = now() WHERE id = $1`, oldKeyID); err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
}
|
||||
var newKeyID string
|
||||
if err = tx.QueryRow(ctx,
|
||||
`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
|
||||
VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
|
||||
"user:"+strings.ToLower(cur.Email), prefix, keyHash, cur.Email, ratePerMin, quotaTotal,
|
||||
).Scan(&newKeyID); err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
if _, err = tx.Exec(ctx,
|
||||
`UPDATE app_user SET api_key_id = $1 WHERE id = $2`, newKeyID, cur.ID); err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
if err = tx.Commit(ctx); err != nil {
|
||||
return "", Account{}, "", err
|
||||
}
|
||||
|
||||
cur.KeyID = newKeyID
|
||||
cur.KeyPrefix = prefix
|
||||
cur.RateLimitPerMin = ratePerMin
|
||||
cur.QuotaTotal = quotaTotal
|
||||
return key, cur, oldKeyID, nil
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package store
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/jackc/pgx/v5/pgxpool"
|
||||
|
||||
"github.com/baicai2026-baicai/goods/api/internal/apikey"
|
||||
)
|
||||
|
||||
func testStore(t *testing.T) *Store {
|
||||
t.Helper()
|
||||
dsn := os.Getenv("OPENGOODS_DATABASE_URL")
|
||||
if dsn == "" {
|
||||
dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
|
||||
defer cancel()
|
||||
pool, err := pgxpool.New(ctx, dsn)
|
||||
if err != nil {
|
||||
t.Skipf("no database: %v", err)
|
||||
}
|
||||
if err := pool.Ping(ctx); err != nil {
|
||||
pool.Close()
|
||||
t.Skipf("database not reachable: %v", err)
|
||||
}
|
||||
var hasUser bool
|
||||
if err := pool.QueryRow(ctx, "SELECT to_regclass('public.app_user') IS NOT NULL").Scan(&hasUser); err != nil || !hasUser {
|
||||
pool.Close()
|
||||
t.Skip("migrations not applied")
|
||||
}
|
||||
t.Cleanup(pool.Close)
|
||||
return New(pool)
|
||||
}
|
||||
|
||||
func TestRegisterAuthenticateRegenerate(t *testing.T) {
|
||||
s := testStore(t)
|
||||
ctx := context.Background()
|
||||
email := fmt.Sprintf("user-%d@example.com", time.Now().UnixNano())
|
||||
|
||||
t.Cleanup(func() {
|
||||
_, _ = s.pool.Exec(ctx, "DELETE FROM app_user WHERE lower(email)=lower($1)", email)
|
||||
_, _ = s.pool.Exec(ctx, "DELETE FROM api_key WHERE owner_email=$1", email)
|
||||
})
|
||||
|
||||
key, acct, err := s.RegisterUser(ctx, email, "supersecret", 300, 100000)
|
||||
if err != nil {
|
||||
t.Fatalf("register: %v", err)
|
||||
}
|
||||
if key == "" || acct.KeyPrefix == "" || acct.QuotaTotal != 100000 || acct.RateLimitPerMin != 300 {
|
||||
t.Fatalf("unexpected account: %+v key=%q", acct, key)
|
||||
}
|
||||
|
||||
// The issued key resolves via the public auth path with its quota attached.
|
||||
k, err := s.APIKeyByHash(ctx, apikey.Hash(key))
|
||||
if err != nil {
|
||||
t.Fatalf("APIKeyByHash: %v", err)
|
||||
}
|
||||
if k.QuotaTotal != 100000 || k.RateLimitPerMin != 300 {
|
||||
t.Fatalf("key metadata mismatch: %+v", k)
|
||||
}
|
||||
|
||||
// Duplicate email is rejected.
|
||||
if _, _, err := s.RegisterUser(ctx, email, "anotherpass", 300, 100000); !errors.Is(err, ErrEmailTaken) {
|
||||
t.Fatalf("expected ErrEmailTaken, got %v", err)
|
||||
}
|
||||
|
||||
// Wrong password fails; correct password authenticates.
|
||||
if _, err := s.Authenticate(ctx, email, "wrong"); !errors.Is(err, ErrNotFound) {
|
||||
t.Fatalf("expected ErrNotFound for bad password, got %v", err)
|
||||
}
|
||||
got, err := s.Authenticate(ctx, email, "supersecret")
|
||||
if err != nil {
|
||||
t.Fatalf("authenticate: %v", err)
|
||||
}
|
||||
if got.KeyPrefix != acct.KeyPrefix {
|
||||
t.Fatalf("authenticate key prefix = %q want %q", got.KeyPrefix, acct.KeyPrefix)
|
||||
}
|
||||
|
||||
// Regeneration revokes the old key and issues a new one.
|
||||
newKey, regen, oldKeyID, err := s.RegenerateKey(ctx, email, "supersecret", 300, 100000)
|
||||
if err != nil {
|
||||
t.Fatalf("regenerate: %v", err)
|
||||
}
|
||||
if newKey == key || oldKeyID != acct.KeyID || regen.KeyID == oldKeyID {
|
||||
t.Fatalf("regenerate did not rotate key: old=%s new=%+v", oldKeyID, regen)
|
||||
}
|
||||
if _, err := s.APIKeyByHash(ctx, apikey.Hash(key)); !errors.Is(err, ErrNotFound) {
|
||||
t.Fatalf("old key should be revoked, got %v", err)
|
||||
}
|
||||
if _, err := s.APIKeyByHash(ctx, apikey.Hash(newKey)); err != nil {
|
||||
t.Fatalf("new key should be active: %v", err)
|
||||
}
|
||||
}
|
||||
@@ -453,6 +453,7 @@ type APIKey struct {
|
||||
ID string
|
||||
Name string
|
||||
RateLimitPerMin int
|
||||
QuotaTotal int64
|
||||
}
|
||||
|
||||
// APIKeyByHash returns the active (non-revoked) key matching a SHA-256 hash,
|
||||
@@ -460,9 +461,9 @@ type APIKey struct {
|
||||
func (s *Store) APIKeyByHash(ctx context.Context, hash string) (*APIKey, error) {
|
||||
var k APIKey
|
||||
err := s.pool.QueryRow(ctx,
|
||||
`SELECT id, name, rate_limit_per_min
|
||||
`SELECT id, name, rate_limit_per_min, quota_total
|
||||
FROM api_key WHERE key_hash = $1 AND revoked_at IS NULL`, hash,
|
||||
).Scan(&k.ID, &k.Name, &k.RateLimitPerMin)
|
||||
).Scan(&k.ID, &k.Name, &k.RateLimitPerMin, &k.QuotaTotal)
|
||||
if errors.Is(err, pgx.ErrNoRows) {
|
||||
return nil, ErrNotFound
|
||||
}
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
DROP TABLE IF EXISTS app_user;
|
||||
|
||||
-- Demote any self-registered keys before restoring the narrower tier check.
|
||||
UPDATE api_key SET tier = 'free' WHERE tier = 'registered';
|
||||
|
||||
ALTER TABLE api_key DROP CONSTRAINT IF EXISTS api_key_tier_chk;
|
||||
ALTER TABLE api_key ADD CONSTRAINT api_key_tier_chk
|
||||
CHECK (tier IN ('free', 'partner', 'internal'));
|
||||
|
||||
ALTER TABLE api_key DROP COLUMN IF EXISTS quota_total;
|
||||
@@ -0,0 +1,27 @@
|
||||
-- Cumulative usage quotas + self-service user registration for the public API.
|
||||
--
|
||||
-- The free anonymous tier is capped at a lifetime number of calls (enforced in
|
||||
-- Redis, keyed by client IP). To keep calling beyond the free quota a caller
|
||||
-- registers an account and self-issues an API key with a higher quota.
|
||||
-- quota_total = 0 means unlimited.
|
||||
--
|
||||
-- Registration is the one place the public server writes to PostgreSQL (it
|
||||
-- inserts an app_user and its api_key); every other public route stays
|
||||
-- read-only. Request counting still lives entirely in Redis.
|
||||
|
||||
ALTER TABLE api_key ADD COLUMN IF NOT EXISTS quota_total BIGINT NOT NULL DEFAULT 0;
|
||||
|
||||
ALTER TABLE api_key DROP CONSTRAINT IF EXISTS api_key_tier_chk;
|
||||
ALTER TABLE api_key ADD CONSTRAINT api_key_tier_chk
|
||||
CHECK (tier IN ('free', 'registered', 'partner', 'internal'));
|
||||
|
||||
CREATE TABLE IF NOT EXISTS app_user (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
email TEXT NOT NULL,
|
||||
password_hash TEXT NOT NULL,
|
||||
api_key_id UUID REFERENCES api_key (id) ON DELETE SET NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- Case-insensitive uniqueness so each email registers at most once.
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS idx_app_user_email ON app_user (lower(email));
|
||||
@@ -1,16 +1,18 @@
|
||||
import { useEffect, useState } from "react";
|
||||
import { Boxes, Search, PlusCircle, Code2 } from "lucide-react";
|
||||
import { Boxes, Search, PlusCircle, Code2, KeyRound } from "lucide-react";
|
||||
import Home from "./components/Home";
|
||||
import ProductView from "./components/ProductView";
|
||||
import Contribute from "./components/Contribute";
|
||||
import ApiDocs from "./components/ApiDocs";
|
||||
import Account from "./components/Account";
|
||||
import { api } from "./api";
|
||||
|
||||
type View =
|
||||
| { name: "home" }
|
||||
| { name: "product"; id: string }
|
||||
| { name: "contribute" }
|
||||
| { name: "api" };
|
||||
| { name: "api" }
|
||||
| { name: "account" };
|
||||
|
||||
export default function App() {
|
||||
const [view, setView] = useState<View>({ name: "home" });
|
||||
@@ -59,6 +61,14 @@ export default function App() {
|
||||
>
|
||||
<Code2 className="w-4 h-4" /> API
|
||||
</button>
|
||||
<button
|
||||
className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
|
||||
view.name === "account" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
|
||||
}`}
|
||||
onClick={() => setView({ name: "account" })}
|
||||
>
|
||||
<KeyRound className="w-4 h-4" /> API 密钥
|
||||
</button>
|
||||
</nav>
|
||||
</div>
|
||||
</header>
|
||||
@@ -77,7 +87,8 @@ export default function App() {
|
||||
{view.name === "contribute" && (
|
||||
<Contribute onDone={() => setView({ name: "home" })} />
|
||||
)}
|
||||
{view.name === "api" && <ApiDocs />}
|
||||
{view.name === "api" && <ApiDocs onRegister={() => setView({ name: "account" })} />}
|
||||
{view.name === "account" && <Account />}
|
||||
</main>
|
||||
|
||||
<footer className="border-t bg-white">
|
||||
|
||||
@@ -36,6 +36,23 @@ export interface Stats {
|
||||
min_score: number;
|
||||
}
|
||||
|
||||
export interface KeyResponse {
|
||||
email: string;
|
||||
api_key: string;
|
||||
key_prefix: string;
|
||||
rate_limit_per_min: number;
|
||||
quota_total: number;
|
||||
}
|
||||
|
||||
export interface AccountInfo {
|
||||
email: string;
|
||||
key_prefix: string;
|
||||
rate_limit_per_min: number;
|
||||
quota_total: number;
|
||||
quota_used: number;
|
||||
quota_remaining: number;
|
||||
}
|
||||
|
||||
export const api = {
|
||||
stats: () => req<Stats>(`/api/v1/stats`),
|
||||
search: (q: string, page = 1, size = 20, filters: SearchFilters = {}) => {
|
||||
@@ -55,4 +72,19 @@ export const api = {
|
||||
method: "POST",
|
||||
body: JSON.stringify(input),
|
||||
}),
|
||||
register: (email: string, password: string) =>
|
||||
req<KeyResponse>(`/api/v1/register`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ email, password }),
|
||||
}),
|
||||
account: (email: string, password: string) =>
|
||||
req<AccountInfo>(`/api/v1/account`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ email, password }),
|
||||
}),
|
||||
regenerate: (email: string, password: string) =>
|
||||
req<KeyResponse>(`/api/v1/account/regenerate`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ email, password }),
|
||||
}),
|
||||
};
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
import { useState } from "react";
|
||||
import { Check, Copy, KeyRound, AlertTriangle } from "lucide-react";
|
||||
import { api, type AccountInfo, type KeyResponse } from "../api";
|
||||
|
||||
function KeyReveal({ data }: { data: KeyResponse }) {
|
||||
const [copied, setCopied] = useState(false);
|
||||
return (
|
||||
<div className="mt-4 rounded-lg border border-emerald-200 bg-emerald-50 p-4">
|
||||
<div className="flex items-start gap-2 text-amber-700 text-sm">
|
||||
<AlertTriangle className="w-4 h-4 mt-0.5 shrink-0" />
|
||||
<span>请立即复制保存此密钥，它只显示这一次，无法再次查看。</span>
|
||||
</div>
|
||||
<div className="mt-3 flex items-center gap-2">
|
||||
<code className="flex-1 break-all bg-white border rounded-md px-3 py-2 text-sm font-mono text-gray-800">
|
||||
{data.api_key}
|
||||
</code>
|
||||
<button
|
||||
onClick={async () => {
|
||||
try {
|
||||
await navigator.clipboard.writeText(data.api_key);
|
||||
setCopied(true);
|
||||
setTimeout(() => setCopied(false), 1200);
|
||||
} catch {
|
||||
/* clipboard unavailable */
|
||||
}
|
||||
}}
|
||||
className="text-gray-400 hover:text-gray-600 shrink-0"
|
||||
title="复制"
|
||||
>
|
||||
{copied ? <Check className="w-5 h-5 text-emerald-600" /> : <Copy className="w-5 h-5" />}
|
||||
</button>
|
||||
</div>
|
||||
<div className="mt-3 text-sm text-gray-600">
|
||||
配额：每分钟 <strong>{data.rate_limit_per_min}</strong> 次 · 累计{" "}
|
||||
<strong>{data.quota_total.toLocaleString()}</strong> 次
|
||||
</div>
|
||||
<div className="mt-2 text-xs text-gray-500">
|
||||
调用时通过请求头携带：
|
||||
<code className="font-mono">X-API-Key: {data.api_key.slice(0, 12)}…</code>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export default function Account() {
|
||||
const [mode, setMode] = useState<"register" | "manage">("register");
|
||||
const [email, setEmail] = useState("");
|
||||
const [password, setPassword] = useState("");
|
||||
const [loading, setLoading] = useState(false);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [issued, setIssued] = useState<KeyResponse | null>(null);
|
||||
const [info, setInfo] = useState<AccountInfo | null>(null);
|
||||
|
||||
const reset = () => {
|
||||
setError(null);
|
||||
setIssued(null);
|
||||
setInfo(null);
|
||||
};
|
||||
|
||||
async function submit(e: React.FormEvent) {
|
||||
e.preventDefault();
|
||||
reset();
|
||||
if (password.length < 8) {
|
||||
setError("密码至少需要 8 位");
|
||||
return;
|
||||
}
|
||||
setLoading(true);
|
||||
try {
|
||||
if (mode === "register") {
|
||||
setIssued(await api.register(email, password));
|
||||
} else {
|
||||
setInfo(await api.account(email, password));
|
||||
}
|
||||
} catch (err) {
|
||||
setError(err instanceof Error ? err.message : "操作失败");
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}
|
||||
|
||||
async function regenerate() {
|
||||
reset();
|
||||
setLoading(true);
|
||||
try {
|
||||
setIssued(await api.regenerate(email, password));
|
||||
} catch (err) {
|
||||
setError(err instanceof Error ? err.message : "操作失败");
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="max-w-xl mx-auto space-y-5">
|
||||
<div className="bg-white border rounded-lg p-5">
|
||||
<h1 className="flex items-center gap-2 text-2xl font-bold text-gray-800">
|
||||
<KeyRound className="w-6 h-6 text-emerald-600" /> API 密钥
|
||||
</h1>
|
||||
<p className="mt-2 text-sm text-gray-600 leading-relaxed">
|
||||
匿名调用免费，但每个来源 IP 累计共 <strong>1000</strong> 次。注册一个账号即可自助领取专属 API
|
||||
密钥，获得更高的每分钟频率与累计调用配额。
|
||||
</p>
|
||||
|
||||
<div className="mt-4 inline-flex rounded-md border bg-gray-50 p-0.5 text-sm">
|
||||
<button
|
||||
className={`px-4 py-1.5 rounded ${
|
||||
mode === "register" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
|
||||
}`}
|
||||
onClick={() => {
|
||||
setMode("register");
|
||||
reset();
|
||||
}}
|
||||
>
|
||||
注册领取
|
||||
</button>
|
||||
<button
|
||||
className={`px-4 py-1.5 rounded ${
|
||||
mode === "manage" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
|
||||
}`}
|
||||
onClick={() => {
|
||||
setMode("manage");
|
||||
reset();
|
||||
}}
|
||||
>
|
||||
查看 / 重置
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<form onSubmit={submit} className="mt-4 space-y-3">
|
||||
<div>
|
||||
<label className="block text-sm text-gray-600 mb-1">邮箱</label>
|
||||
<input
|
||||
type="email"
|
||||
required
|
||||
value={email}
|
||||
onChange={(e) => setEmail(e.target.value)}
|
||||
placeholder="you@example.com"
|
||||
className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
|
||||
/>
|
||||
</div>
|
||||
<div>
|
||||
<label className="block text-sm text-gray-600 mb-1">密码（至少 8 位）</label>
|
||||
<input
|
||||
type="password"
|
||||
required
|
||||
value={password}
|
||||
onChange={(e) => setPassword(e.target.value)}
|
||||
placeholder="••••••••"
|
||||
className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
|
||||
/>
|
||||
</div>
|
||||
{error && <div className="text-sm text-red-600">{error}</div>}
|
||||
<button
|
||||
type="submit"
|
||||
disabled={loading}
|
||||
className="w-full bg-emerald-600 text-white rounded-md py-2 text-sm font-medium hover:bg-emerald-700 disabled:opacity-50"
|
||||
>
|
||||
{loading ? "处理中…" : mode === "register" ? "注册并领取密钥" : "查询账号"}
|
||||
</button>
|
||||
</form>
|
||||
|
||||
{issued && <KeyReveal data={issued} />}
|
||||
|
||||
{info && (
|
||||
<div className="mt-4 rounded-lg border bg-gray-50 p-4 text-sm text-gray-700 space-y-1.5">
|
||||
<div>
|
||||
邮箱：<span className="font-medium">{info.email}</span>
|
||||
</div>
|
||||
<div>
|
||||
密钥前缀：<code className="font-mono">{info.key_prefix}…</code>
|
||||
</div>
|
||||
<div>
|
||||
每分钟频率：<strong>{info.rate_limit_per_min}</strong> 次
|
||||
</div>
|
||||
<div>
|
||||
累计配额：已用 <strong>{info.quota_used.toLocaleString()}</strong> /{" "}
|
||||
{info.quota_total.toLocaleString()} 次（剩余{" "}
|
||||
<strong className="text-emerald-600">{info.quota_remaining.toLocaleString()}</strong>）
|
||||
</div>
|
||||
<button
|
||||
onClick={regenerate}
|
||||
disabled={loading}
|
||||
className="mt-2 text-emerald-600 hover:underline disabled:opacity-50"
|
||||
>
|
||||
忘记密钥？重置并生成新密钥
|
||||
</button>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -102,7 +102,7 @@ function Endpoint({
|
||||
);
|
||||
}
|
||||
|
||||
export default function ApiDocs() {
|
||||
export default function ApiDocs({ onRegister }: { onRegister?: () => void }) {
|
||||
return (
|
||||
<div className="space-y-5">
|
||||
<div className="bg-white border rounded-lg p-5">
|
||||
@@ -117,7 +117,11 @@ export default function ApiDocs() {
|
||||
基础地址：<code className="font-mono bg-gray-100 rounded px-1.5 py-0.5">{BASE}</code>
|
||||
</div>
|
||||
<ul className="mt-2 list-disc pl-5 text-gray-600 space-y-1">
|
||||
<li>无需 API Key / Token 即可直接 GET；带 Key 可获得更高频率上限（见下文「鉴权与限流」）。</li>
|
||||
<li>
|
||||
无需 API Key / Token 即可直接 GET；匿名调用按来源 IP 累计共 <strong>1000</strong> 次，
|
||||
用满后需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
|
||||
领取更高配额密钥（见下文「鉴权与配额」）。
|
||||
</li>
|
||||
<li>
|
||||
分页参数 <code className="font-mono">page</code>（默认 1）、
|
||||
<code className="font-mono">size</code>（默认 20，最大 100）。
|
||||
@@ -132,10 +136,13 @@ export default function ApiDocs() {
|
||||
</div>
|
||||
|
||||
<div className="bg-white border rounded-lg p-5">
|
||||
<h2 className="text-lg font-semibold text-gray-800">鉴权与限流</h2>
|
||||
<h2 className="text-lg font-semibold text-gray-800">鉴权与配额</h2>
|
||||
<p className="mt-2 text-gray-600 text-sm leading-relaxed">
|
||||
API 默认<strong>匿名可用</strong>：无需任何凭证即可调用，按来源 IP 计入一个较低的默认频率额度。
|
||||
如需更高额度并让用量归属到你，可在运营方申请一枚 API Key，请求时通过请求头携带：
|
||||
API 默认<strong>匿名可用</strong>：无需任何凭证即可调用，但按来源 IP 计一个
|
||||
<strong>累计总配额（共 1000 次）</strong>，用满后返回
|
||||
<code className="font-mono">403</code>（错误码 <code className="font-mono">quota_exhausted</code>），
|
||||
需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
|
||||
自助领取更高配额的 API Key。注册得到的密钥拥有更高的每分钟频率与累计调用配额，请求时通过请求头携带：
|
||||
</p>
|
||||
<div className="mt-3">
|
||||
<Code>{`# 二选一
|
||||
@@ -143,7 +150,7 @@ curl -H "X-API-Key: og_live_xxxxxxxx" ${BASE}/products/search?q=牛奶
|
||||
curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛奶`}</Code>
|
||||
</div>
|
||||
<p className="mt-3 text-gray-600 text-sm leading-relaxed">
|
||||
采用<strong>固定窗口</strong>限流（每分钟）。每个响应都会回写以下响应头，便于客户端自适应：
|
||||
同时采用<strong>每分钟固定窗口</strong>频率限制与<strong>累计总配额</strong>两层控制。每个响应都会回写以下响应头，便于客户端自适应：
|
||||
</p>
|
||||
<table className="mt-3 w-full text-sm">
|
||||
<thead className="text-gray-400 text-left">
|
||||
@@ -169,12 +176,26 @@ curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛
|
||||
<td className="pr-4 py-0.5 font-mono text-gray-700">Retry-After</td>
|
||||
<td className="py-0.5 text-gray-600">超额时返回，建议等待的秒数</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="pr-4 py-0.5 font-mono text-gray-700">X-Quota-Limit</td>
|
||||
<td className="py-0.5 text-gray-600">累计总配额上限</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="pr-4 py-0.5 font-mono text-gray-700">X-Quota-Used</td>
|
||||
<td className="py-0.5 text-gray-600">已累计使用的调用次数</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="pr-4 py-0.5 font-mono text-gray-700">X-Quota-Remaining</td>
|
||||
<td className="py-0.5 text-gray-600">累计配额剩余可用次数</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p className="mt-3 text-gray-600 text-sm leading-relaxed">
|
||||
超过额度返回 <code className="font-mono">429 Too Many Requests</code>，错误码
|
||||
<code className="font-mono">rate_limited</code>；无效或已吊销的 Key 返回
|
||||
<code className="font-mono">401</code>，错误码 <code className="font-mono">invalid_api_key</code>。
|
||||
每分钟超额返回 <code className="font-mono">429 Too Many Requests</code>（错误码
|
||||
<code className="font-mono">rate_limited</code>）；累计配额用尽返回
|
||||
<code className="font-mono">403</code>（错误码 <code className="font-mono">quota_exhausted</code>）；
|
||||
无效或已吊销的 Key 返回 <code className="font-mono">401</code>（错误码
|
||||
<code className="font-mono">invalid_api_key</code>）。
|
||||
</p>
|
||||
</div>
|
||||
|
||||
@@ -322,6 +343,70 @@ curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛
|
||||
}`}
|
||||
/>
|
||||
|
||||
<Endpoint
|
||||
method="POST"
|
||||
path="/api/v1/register"
|
||||
title="注册账号并领取 API 密钥"
|
||||
desc="用邮箱 + 密码（至少 8 位）注册，自助领取一枚更高配额的 API 密钥。明文密钥只在本次响应返回一次，请妥善保存。"
|
||||
params={[
|
||||
{ name: "email", required: true, desc: "邮箱（唯一）" },
|
||||
{ name: "password", required: true, desc: "密码，至少 8 位" },
|
||||
]}
|
||||
example={`curl -X POST ${BASE}/register \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{"email":"you@example.com","password":"your-password"}'`}
|
||||
response={`{
|
||||
"email": "you@example.com",
|
||||
"api_key": "og_live_xxxxxxxxxxxx",
|
||||
"key_prefix": "og_live_xxxx",
|
||||
"rate_limit_per_min": 300,
|
||||
"quota_total": 100000
|
||||
}`}
|
||||
/>
|
||||
|
||||
<Endpoint
|
||||
method="POST"
|
||||
path="/api/v1/account"
|
||||
title="查看账号与配额用量"
|
||||
desc="用邮箱 + 密码查询当前密钥前缀、频率/累计配额上限及已用量（不返回明文密钥）。"
|
||||
params={[
|
||||
{ name: "email", required: true, desc: "注册邮箱" },
|
||||
{ name: "password", required: true, desc: "账号密码" },
|
||||
]}
|
||||
example={`curl -X POST ${BASE}/account \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{"email":"you@example.com","password":"your-password"}'`}
|
||||
response={`{
|
||||
"email": "you@example.com",
|
||||
"key_prefix": "og_live_xxxx",
|
||||
"rate_limit_per_min": 300,
|
||||
"quota_total": 100000,
|
||||
"quota_used": 1234,
|
||||
"quota_remaining": 98766
|
||||
}`}
|
||||
/>
|
||||
|
||||
<Endpoint
|
||||
method="POST"
|
||||
path="/api/v1/account/regenerate"
|
||||
title="重置 API 密钥"
|
||||
desc="吊销当前密钥并生成新密钥（累计用量会延续，不会因重置而清零）。明文新密钥只返回一次。"
|
||||
params={[
|
||||
{ name: "email", required: true, desc: "注册邮箱" },
|
||||
{ name: "password", required: true, desc: "账号密码" },
|
||||
]}
|
||||
example={`curl -X POST ${BASE}/account/regenerate \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-d '{"email":"you@example.com","password":"your-password"}'`}
|
||||
response={`{
|
||||
"email": "you@example.com",
|
||||
"api_key": "og_live_yyyyyyyyyyyy",
|
||||
"key_prefix": "og_live_yyyy",
|
||||
"rate_limit_per_min": 300,
|
||||
"quota_total": 100000
|
||||
}`}
|
||||
/>
|
||||
|
||||
<div className="text-xs text-gray-400 leading-relaxed">
|
||||
数据可能存在误差或滞后，按「现状」提供，不构成医疗/购买建议。商品资料版权归各原始来源所有，
|
||||
请遵循其许可（如 OpenFoodFacts 的 ODbL）。
|
||||
|
||||
Reference in New Issue
Block a user