API 接口文档

标准响应结构

所有 API 响应均采用统一的 JSON 格式，包含以下标准字段：

{
  "success": boolean,        // 请求是否成功
  "data": object | array,    // 响应数据（成功时）
  "error": string,           // 错误信息（失败时）
  "message": string,         // 详细描述（可选）
  "timestamp": string        // 响应时间戳（ISO 8601格式）
}

开奖号码格式

不同类型的彩种，code 字段的格式有所不同：

"code": "1,2,3,4,5"

"code": {
  "first_prize": "12345",
  "second_prize": "67890",
  "special_prizes": ["11111", "22222"]
  // ... 更多奖项
}

"code": {
  "code": "1,2,3,4,5",
  "code_block": "23697768",
  "code_hash": "0xfac6573055cc28809..."
}

分页响应

支持分页的接口会额外返回 pagination 对象：

"pagination": {
  "page": 1,           // 当前页码
  "limit": 20,         // 每页条数
  "total": 1000,       // 总记录数
  "totalPages": 50     // 总页数
}

HTTP 状态码

错误响应格式

{
  "success": false,
  "error": "INVALID_LOTTERY_CODE",
  "message": "彩种代码不存在或格式错误",
  "details": {
    "lottery_code": "INVALID_CODE",
    "valid_codes_example": ["CQSSC", "HNFC", "BJPK10"]
  },
  "timestamp": "2025-10-31T22:35:00Z"
}

常见错误代码

// 使用 async/await
async function getLotteryResults(lotteryCode, page = 1, limit = 20) {
  try {
    const response = await fetch(
      `https://lottery.langne.com/api/lottery-results?lottery_code=${lotteryCode}&page=${page}&limit=${limit}`
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    
    if (data.success) {
      console.log(`获取到 ${data.data.length} 条记录`);
      return data.data;
    } else {
      console.error('请求失败:', data.error);
      return null;
    }
  } catch (error) {
    console.error('网络错误:', error);
    return null;
  }
}

// 使用示例
getLotteryResults('CQSSC', 1, 50).then(results => {
  if (results) {
    results.forEach(item => {
      console.log(`期号: ${item.issue}, 号码: ${item.code}`);
    });
  }
});

// 使用 axios
const axios = require('axios');

axios.get('https://lottery.langne.com/api/lottery-results', {
  params: {
    lottery_code: 'CQSSC',
    page: 1,
    limit: 20
  }
})
.then(response => {
  const data = response.data;
  if (data.success) {
    console.log('数据:', data.data);
  }
})
.catch(error => {
  console.error('Error:', error);
});

Python

import requests
from typing import Optional, Dict, List

class LotteryAPI:
    BASE_URL = "https://lottery.langne.com"
    
    def __init__(self):
        self.session = requests.Session()
        self.session.headers.update({
            'Accept': 'application/json',
            'User-Agent': 'LotteryClient/1.0'
        })
    
    def get_lottery_types(self, active: bool = True) -> Optional[List[Dict]]:
        """获取彩种列表"""
        try:
            response = self.session.get(
                f"{self.BASE_URL}/api/lottery-types",
                params={'active': active}
            )
            response.raise_for_status()
            data = response.json()
            return data.get('data') if data.get('success') else None
        except requests.RequestException as e:
            print(f"请求失败: {e}")
            return None
    
    def get_lottery_results(
        self, 
        lottery_code: str, 
        page: int = 1, 
        limit: int = 20,
        date: Optional[str] = None
    ) -> Optional[Dict]:
        """获取开奖结果"""
        params = {
            'lottery_code': lottery_code,
            'page': page,
            'limit': limit
        }
        if date:
            params['date'] = date
        
        try:
            response = self.session.get(
                f"{self.BASE_URL}/api/lottery-results",
                params=params
            )
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            print(f"请求失败: {e}")
            return None

# 使用示例
if __name__ == "__main__":
    api = LotteryAPI()
    
    # 获取彩种列表
    types = api.get_lottery_types()
    if types:
        print(f"共有 {len(types)} 个彩种")
    
    # 获取开奖结果
    results = api.get_lottery_results('CQSSC', page=1, limit=10)
    if results and results.get('success'):
        for item in results['data']:
            print(f"期号: {item['issue']}, 号码: {item['code']}")

PHP

<?php

class LotteryAPI {
    private $baseUrl = 'https://lottery.langne.com';
    
    /**
     * 获取彩种列表
     */
    public function getLotteryTypes($active = true) {
        $url = $this->baseUrl . '/api/lottery-types';
        $params = ['active' => $active ? 'true' : 'false'];
        
        return $this->request($url, $params);
    }
    
    /**
     * 获取开奖结果
     */
    public function getLotteryResults($lotteryCode, $page = 1, $limit = 20, $date = null) {
        $url = $this->baseUrl . '/api/lottery-results';
        $params = [
            'lottery_code' => $lotteryCode,
            'page' => $page,
            'limit' => $limit
        ];
        
        if ($date) {
            $params['date'] = $date;
        }
        
        return $this->request($url, $params);
    }
    
    /**
     * 获取最新一期
     */
    public function getLatestResult($lotteryCode) {
        $url = $this->baseUrl . '/api/lottery-results/latest';
        $params = ['lottery_code' => $lotteryCode];
        
        return $this->request($url, $params);
    }
    
    /**
     * 发送请求
     */
    private function request($url, $params = []) {
        $fullUrl = $url . '?' . http_build_query($params);
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $fullUrl);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Accept: application/json',
            'User-Agent: LotteryClient/1.0'
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            return ['success' => false, 'error' => 'HTTP Error: ' . $httpCode];
        }
        
        return json_decode($response, true);
    }
}

// 使用示例
$api = new LotteryAPI();

// 获取彩种列表
$types = $api->getLotteryTypes();
if ($types['success']) {
    echo "共有 " . count($types['data']) . " 个彩种\n";
}

// 获取开奖结果
$results = $api->getLotteryResults('CQSSC', 1, 20);
if ($results['success']) {
    foreach ($results['data'] as $item) {
        echo "期号: {$item['issue']}, 号码: {$item['code']}\n";
    }
}

// 获取最新一期
$latest = $api->getLatestResult('CQSSC');
if ($latest['success']) {
    echo "最新开奖: " . json_encode($latest['data'], JSON_UNESCAPED_UNICODE) . "\n";
}
?>

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class LotteryAPI {
    private static final String BASE_URL = "https://lottery.langne.com";
    private final HttpClient client;
    private final Gson gson;
    
    public LotteryAPI() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }
    
    /**
     * 获取开奖结果
     */
    public JsonObject getLotteryResults(String lotteryCode, int page, int limit) {
        String url = String.format(
            "%s/api/lottery-results?lottery_code=%s&page=%d&limit=%d",
            BASE_URL, lotteryCode, page, limit
        );
        
        try {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Accept", "application/json")
                .GET()
                .build();
            
            HttpResponse<String> response = client.send(
                request, 
                HttpResponse.BodyHandlers.ofString()
            );
            
            if (response.statusCode() == 200) {
                return gson.fromJson(response.body(), JsonObject.class);
            } else {
                System.err.println("HTTP Error: " + response.statusCode());
                return null;
            }
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }
    
    /**
     * 使用示例
     */
    public static void main(String[] args) {
        LotteryAPI api = new LotteryAPI();
        JsonObject results = api.getLotteryResults("CQSSC", 1, 20);
        
        if (results != null && results.get("success").getAsBoolean()) {
            System.out.println("获取成功:");
            System.out.println(results.toString());
        }
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

const BaseURL = "https://lottery.langne.com"

type LotteryAPI struct {
    client *http.Client
}

type APIResponse struct {
    Success bool        `json:"success"`
    Data    interface{} `json:"data"`
    Error   string      `json:"error,omitempty"`
}

func NewLotteryAPI() *LotteryAPI {
    return &LotteryAPI{
        client: &http.Client{},
    }
}

// 获取开奖结果
func (api *LotteryAPI) GetLotteryResults(lotteryCode string, page, limit int) (*APIResponse, error) {
    params := url.Values{}
    params.Add("lottery_code", lotteryCode)
    params.Add("page", fmt.Sprintf("%d", page))
    params.Add("limit", fmt.Sprintf("%d", limit))
    
    apiURL := fmt.Sprintf("%s/api/lottery-results?%s", BaseURL, params.Encode())
    
    req, err := http.NewRequest("GET", apiURL, nil)
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Accept", "application/json")
    
    resp, err := api.client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
    
    var result APIResponse
    err = json.Unmarshal(body, &result)
    if err != nil {
        return nil, err
    }
    
    return &result, nil
}

func main() {
    api := NewLotteryAPI()
    
    results, err := api.GetLotteryResults("CQSSC", 1, 20)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    if results.Success {
        fmt.Println("获取成功:", results.Data)
    } else {
        fmt.Println("请求失败:", results.Error)
    }
}

🚀 性能优化建议

• ✓使用缓存：对于不频繁变化的数据（如彩种列表），建议在客户端缓存 24 小时
• ✓合理分页：单次请求的 limit 不宜过大，建议 20-50 之间，避免影响性能
• ✓并发控制：如需获取多个彩种数据，建议使用 Promise.all 或类似并发控制机制
• ✓数据更新频率：开奖结果建议每 1-2 分钟刷新一次即可

⚠️ 错误处理建议

• ✓检查 success 字段：始终检查响应中的 success 字段，而不仅仅是 HTTP 状态码
• ✓实现重试机制：对于网络错误或 5xx 错误，建议实现指数退避的重试策略
• ✓优雅降级：API 请求失败时，应提供友好的错误提示，避免应用崩溃
• ✓日志记录：记录所有 API 请求和响应，便于排查问题

🔒 安全建议

• ✓使用 HTTPS：始终使用 HTTPS 协议访问 API
• ✓输入验证：在客户端验证用户输入，避免发送无效请求
• ✓避免暴露敏感信息：不要在前端代码或日志中暴露敏感业务逻辑

💡 开发建议

• ✓封装 API 客户端：建议将 API 调用封装成独立的客户端类或模块
• ✓类型定义：使用 TypeScript 或类似工具定义响应数据的类型
• ✓版本控制：虽然当前无需指定版本，但建议在代码中记录使用的 API 版本
• ✓单元测试：为 API 调用编写单元测试，确保代码质量