D10 零基础速成笔记

老板说"进来给你发币去实战"，这很正常：交易所希望你用用户的眼睛把业务走一遍。但交易所员工有几条线，跨过去就不是技术问题了。先把线认清，再动手。

测试网是交易所自己搭的一套"练习场"：界面、下单接口、撮合都是真的，钱是假的。D4 的模拟盘是你在本地假装成交，测试网是交易所真的在帮你撮合。

网址、注册方式、赠送的假币数量和规则经常变，以各家官网文档为准。访问任何交易所网站，都要遵守你所在地和公司的规定。入职以后，以公司自己的测试环境为准：你们自己的交易所一定有测试或预发环境，问带你的同事要地址和测试账号。

• 选一家同时有现货和合约测试环境、并且有下单接口的
• 拿到假币后，先截图记下初始余额（后面对账用）
• 在测试网上建一个 API Key，按第 1 节的三条规矩设置权限（第 9 节会用）

各家交易所的永续合约界面布局大同小异，都是七块：顶部行情栏、K 线、订单簿、最近成交、下单面板、仓位栏、下面几个记录标签页。认得这七块，换哪家都不慌。

+---------------------------------------------------------------------+
| [1] BTCUSDT Perp | Last | Mark | Index | Funding + countdown | 24h  |
+-----------------------------+--------------+------------------------+
| [2] Chart (candles)         | [3] Order    | [5] Order form         |
|                             |     book     |  Isolated/Cross | 5x   |
|                             +--------------+  Limit/Market/Stop     |
|                             | [4] Recent   |  Price  Qty  TP/SL     |
|                             |     trades   |  Reduce-only Post-only |
|                             |              | [Open Long][Open Short]|
+-----------------------------+--------------+------------------------+
| [6] Positions: size entry mark liq margin ratio uPnL ROE            |
+---------------------------------------------------------------------+
| [7] Open orders | Order history | Trade history | Transaction log   |
+---------------------------------------------------------------------+

1 顶部行情栏：交易对（Perp = 永续）、最新价、标记价格、指数价格、资金费率和结算倒计时、24 小时成交量 · 2 K 线 · 3 订单簿 · 4 最近成交 · 5 下单面板：逐仓 / 全仓、杠杆、限价 / 市价 / 条件单、价格、数量、止盈止损、只减仓、只做挂单、开多 / 开空 · 6 仓位栏：数量、开仓均价、标记价格、强平价、保证金、保证金率、未实现盈亏、收益率 · 7 当前委托 / 历史委托 / 成交记录 / 资金流水。

先从现货开始：没有杠杆、没有强平，最适合练"下单以后钱去哪儿了"。每个练习都先把预期算出来，再去界面上核对。

合约练习的目标只有一个：界面上的每个数，你都能自己算出来，或者说得出为什么算不出来。下面的例子统一用：BTCUSDT 永续，逐仓 5 倍，限价开多 0.01 BTC @ 60,000。

真正干过的人，都知道交易所会因为哪些原因拒单。今天故意把每种错都犯一遍，看交易所怎么回。以后线上用户说"下不了单"，你第一反应就知道查哪几项。

下面这张表里的原因代码，是我们自己起的名字，不是哪家交易所的真实错误码（各家的错误码和提示文字都不一样）。它们是简化版规则，真实规则各家不同，细节以文档为准。回到总页 D10 的编程题 checkOrder，就是把这张表写成代码：下单前自己先挡一遍，别等交易所来拒。

行话不是为了装，是为了说得准。"价格不对"可能指五种不同的问题，"最新价插针、标记价没动"只指一种。

公开接口不需要账号，谁都能调。你可以用它拿到真实的盘口、K 线、标记价格和资金费率，把 D2、D3、D9 学的公式用真数据算一遍。

下面用 Binance 的公开接口举例（路径、参数和返回字段以官方文档为准；把域名换成测试网的，就能拿到测试网的数据）：

# 1. 盘口：买卖各 5 档（D3）
curl 'https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=5'

# 2. K 线：最近 3 根 1 小时 K 线（D3），每根是一个数组：
#    [开盘时间, 开, 高, 低, 收, 成交量, 收盘时间, ...]
curl 'https://api.binance.com/api/v3/klines?symbol=BTCUSDT&interval=1h&limit=3'

# 3. 交易规则：tickSize、lotSize、最小下单金额都在 filters 里（D2）
curl 'https://api.binance.com/api/v3/exchangeInfo?symbol=BTCUSDT'

# 4. 永续合约：标记价格、指数价格、当前资金费率、下次结算时间（D2）
curl 'https://fapi.binance.com/fapi/v1/premiumIndex?symbol=BTCUSDT'

# 5. 永续合约：最近 3 次资金费率历史（D9 资金费率套利要用）
curl 'https://fapi.binance.com/fapi/v1/fundingRate?symbol=BTCUSDT&limit=3'

1 depth 盘口 · 2 klines K 线 · 3 exchangeInfo 交易规则 · 4 premiumIndex 标记价格和资金费率 · 5 fundingRate 资金费率历史。网络连不上时，先确认你所在的网络环境是否允许访问，不要为了练习去绕公司的网络规定。

Java 版本（JDK 11 起自带 HttpClient；解析 JSON 用 D6 已经加过依赖的 Jackson，它是 Java 里最常用的 JSON 库）：

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.math.BigDecimal;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PublicRest {
    public static void main(String[] args) throws Exception {
        HttpClient http = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder(
                URI.create("https://fapi.binance.com/fapi/v1/premiumIndex?symbol=BTCUSDT")).build();
        String body = http.send(req, HttpResponse.BodyHandlers.ofString()).body();

        JsonNode n = new ObjectMapper().readTree(body);
        BigDecimal mark = new BigDecimal(n.path("markPrice").asText());        // 价格是字符串，直接进 BigDecimal
        BigDecimal rate = new BigDecimal(n.path("lastFundingRate").asText());
        BigDecimal qty  = new BigDecimal("0.01");
        // 资金费 = 仓位价值 × 费率；正数表示多头付钱
        System.out.println("标记价 " + mark + "，0.01 BTC 多单下次资金费 " + mark.multiply(qty).multiply(rate));
    }
}

下单、查单、撤单要证明"这个请求真是你发的，而且中途没被改过"。办法是签名：用只有你和交易所知道的密钥，给请求内容算一个指纹，一起发过去。

自己在终端验证一下（输出应该是 c8db…6b71）：

echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" \
  | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"

echo -n：不要在末尾加换行（多一个换行，签名就不对了，这是最常见的签名错误之一）。这对示例密钥是文档公开的，不是任何人的真实密钥。

下面的 TestnetClient 是 D5 Exchange 接口的真实实现，连的是现货测试网。上层的 placeSafely、Reconciler 一行都不用改，这就是 D5 先抽接口的好处。Order、Side、RemoteOrder 用 D4 / D5 定义好的，名字和参数顺序都一样。

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.math.BigDecimal;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpTimeoutException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.*;
import java.util.concurrent.TimeoutException;
import java.util.stream.Collectors;

/** 现货测试网上的 Exchange 实现。以 Binance 现货测试网为例，路径、参数、错误码以官方文档为准 */
public class TestnetClient implements Exchange {
    private static final String BASE = "https://testnet.binance.vision";
    private final String apiKey = System.getenv("TESTNET_API_KEY");       // 密钥只从环境变量读，绝不写进代码
    private final String secret = System.getenv("TESTNET_API_SECRET");
    private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(3)).build();
    private final ObjectMapper json = new ObjectMapper();
    private final String symbol;

    public TestnetClient(String symbol) {
        if (apiKey == null || secret == null)
            throw new IllegalStateException("先设置环境变量 TESTNET_API_KEY 和 TESTNET_API_SECRET");
        this.symbol = symbol;
    }

    @Override
    public Order place(Order o) throws TimeoutException {
        Map<String, String> p = new LinkedHashMap<>();       // LinkedHashMap：保持参数顺序
        p.put("symbol", symbol);
        p.put("side", o.side().name());                     // BUY / SELL
        p.put("type", "LIMIT");
        p.put("timeInForce", "GTC");                        // 一直挂着，直到成交或撤单
        p.put("quantity", o.qty().toPlainString());         // toPlainString：避免 1E-3 这种科学计数法
        p.put("price", o.price().toPlainString());
        p.put("newClientOrderId", o.clientOid());           // 我们自己的编号，D5 的 ClientOid.of(...)
        send("POST", "/api/v3/order", p);                   // 被拒会抛异常；超时抛 TimeoutException
        return o;
    }

    @Override
    public Optional<RemoteOrder> query(String clientOid) {
        Map<String, String> p = new LinkedHashMap<>();
        p.put("symbol", symbol);
        p.put("origClientOrderId", clientOid);              // 按我们的编号查，不需要交易所的 orderId
        try {
            return Optional.of(toRemote(send("GET", "/api/v3/order", p)));
        } catch (NotFound e) {
            return Optional.empty();                        // 交易所确实没有这张单
        } catch (TimeoutException e) {
            // 查询超时 ≠ 查不到。绝不能当成"没有"去重下，交给上层稍后重试
            throw new IllegalStateException("查单超时，稍后重试: " + clientOid, e);
        }
    }

    @Override
    public void cancel(String clientOid) {
        Map<String, String> p = new LinkedHashMap<>();
        p.put("symbol", symbol);
        p.put("origClientOrderId", clientOid);
        try {
            send("DELETE", "/api/v3/order", p);
        } catch (NotFound e) {
            // 已经成交或已经撤掉了：撤单是幂等的，不算错
        } catch (TimeoutException e) {
            throw new IllegalStateException("撤单超时，稍后按编号查一下再决定: " + clientOid, e);
        }
    }

    @Override
    public List<RemoteOrder> openOrders() {
        Map<String, String> p = new LinkedHashMap<>();
        p.put("symbol", symbol);
        try {
            List<RemoteOrder> out = new ArrayList<>();
            for (JsonNode n : send("GET", "/api/v3/openOrders", p)) out.add(toRemote(n));
            return out;
        } catch (TimeoutException e) {
            throw new IllegalStateException("查挂单超时，稍后重试", e);
        }
    }

    /** 统一发请求：加 recvWindow 和 timestamp → 签名 → 带上 API Key 发出去 */
    private JsonNode send(String method, String path, Map<String, String> params) throws TimeoutException {
        params.put("recvWindow", "5000");
        params.put("timestamp", String.valueOf(System.currentTimeMillis()));
        String query = params.entrySet().stream()
                .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
                .collect(Collectors.joining("&"));
        String url = BASE + path + "?" + query + "&signature=" + hmacSha256(secret, query);  // 签的和发的是同一串
        HttpRequest req = HttpRequest.newBuilder(URI.create(url))
                .timeout(Duration.ofSeconds(3))
                .header("X-MBX-APIKEY", apiKey)
                .method(method, HttpRequest.BodyPublishers.noBody())
                .build();
        try {
            HttpResponse<String> resp = http.send(req, HttpResponse.BodyHandlers.ofString());
            JsonNode body = json.readTree(resp.body());
            if (resp.statusCode() == 200) return body;
            int code = body.path("code").asInt();
            if (code == -2013 || code == -2011) throw new NotFound();   // Binance：订单不存在 / 撤单时找不到这张单
            throw new IllegalStateException("交易所拒绝: " + resp.body());
        } catch (HttpTimeoutException e) {
            throw new TimeoutException("请求超时，不知道成没成: " + path);   // 交给 D5 的 placeSafely 按编号去查
        } catch (IOException e) {
            throw new IllegalStateException(e);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException(e);
        }
    }

    static String hmacSha256(String secret, String data) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            return HexFormat.of().formatHex(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));   // HexFormat：JDK 17
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }

    /** 交易所的返回 → D5 的 RemoteOrder；状态翻译成 D5 用的四种 */
    private RemoteOrder toRemote(JsonNode n) {
        String oid = n.path("clientOrderId").asText();
        Order o = new Order(oid, Side.valueOf(n.path("side").asText()),
                new BigDecimal(n.path("price").asText()), new BigDecimal(n.path("origQty").asText()), levelOf(oid));
        String status = switch (n.path("status").asText()) {
            case "NEW" -> "OPEN";
            case "PARTIALLY_FILLED" -> "PARTIALLY_FILLED";
            case "FILLED" -> "FILLED";
            default -> "CANCELED";                          // CANCELED / EXPIRED / REJECTED 都算"不在挂了"
        };
        return new RemoteOrder(o, status);
    }

    /** G1-3-B-7 → 3；不是我们起的编号（比如网页上手动下的单）返回 -1 */
    private static int levelOf(String oid) {
        String[] a = oid.split("-");
        try { return a.length == 4 ? Integer.parseInt(a[1]) : -1; }
        catch (NumberFormatException e) { return -1; }
    }

    private static class NotFound extends RuntimeException {}
}

跑一下：挂一张不会成交的单 → 查 → 撤 → 再查。价格取测试网当前价的九折左右，数量用规则允许的值。

import java.math.BigDecimal;

public class TestnetDemo {
    public static void main(String[] args) throws Exception {
        Exchange ex = new TestnetClient("BTCUSDT");
        String oid = ClientOid.of("T1", 0, Side.BUY, 1);                   // "T1-0-B-1"，D5 的编号规则
        Order o = new Order(oid, Side.BUY, new BigDecimal("54000.00"), new BigDecimal("0.00100"), 0);
        ex.place(o);
        System.out.println(ex.query(oid));   // 期望：status=OPEN
        ex.cancel(oid);
        System.out.println(ex.query(oid));   // 期望：status=CANCELED
        ex.cancel(oid);                      // 再撤一次：不报错（幂等）
    }
}
// 运行前：export TESTNET_API_KEY=...  export TESTNET_API_SECRET=...（只在终端里设，不写进任何文件）

跑完以后去测试网网页的历史委托里，找到编号 T1-0-B-1 的那张单，状态应该是已撤销。网页上能看到你程序下的单，说明整条链路通了。

D3、D4 用的是公开推送，所有人收到的都一样。你自己的订单什么时候成交，要靠私有推送来告诉你。这一节是进阶，可以选做。

接入步骤（每一步都能单独跑通再做下一步）：

1. 下单换实现：D4 的 BotLoop 里直接用的是 PaperMatcher。把"下单"改成调 Exchange.place，传进去的是 new TestnetClient("BTCUSDT")；PaperMatcher.onTrade 不再需要，成交改由下一步产生。
2. 成交从交易所来：第一版用轮询，发现 FILLED 就包成 D4 的 Fill 放进 BotLoop 的队列（代码见下）。
3. 去重：同一张单可能被连续两次轮询都看到 FILLED，事件循环里按 clientOid 去重，处理过的直接跳过（D6、D7 的幂等）。
4. 启动先对账：每次启动先跑 D5 的 Reconciler，本地和交易所对齐了再开始挂新单。
5. 一键停：写一个"撤掉本网格所有挂单"的方法（用 openOrders + ClientOid.belongsTo 过滤），跑实盘前必须有。

// 第一版成交来源：每 2 秒轮询一次本地认为还在挂的单
ScheduledExecutorService poller = Executors.newSingleThreadScheduledExecutor();
poller.scheduleAtFixedRate(() -> {
    for (Order o : List.copyOf(local.openOrders())) {                 // local 是 D5 的 LocalBook
        exchange.query(o.clientOid()).ifPresent(r -> {
            if (r.status().equals("FILLED"))
                loop.submit(new Fill(o.clientOid(), o.side(), o.level(), o.price(), o.qty(), "FILLED"));
        });                                                            // 只放进队列，不在这个线程里改状态（D4 第 8 节）
    }
}, 0, 2, TimeUnit.SECONDS);

这段代码里查询超时会抛异常，而 scheduleAtFixedRate 遇到没捕获的异常会悄悄停止后续执行。真实代码要在循环体外包一层 try-catch，打日志后继续。

按下面的顺序做，每一步都记下一个数字。数字填到总页 D10 的实操记录表里（保存在你这台浏览器上），入职以后拿到公司的币再走一遍，对比两边。

记录表在这里：七日冲刺 D10 → 实操记录表。每一行分"自己先算"和"界面实际"两栏，差不到 0.5% 会自动显示对上了。记录项是：现货限价买单冻结金额、合约开仓保证金、强平价、某一时刻的未实现盈亏、一次资金费扣款、已实现盈亏、开仓手续费、平仓手续费，最后一行写被拒过的原因代码。

这些问题的共同点：先说你自己做过什么、看到了什么数，再问一个具体的点。比"能给我讲讲系统架构吗"好回答得多，也显得你是做过功课的。

今天用到的词，包括前几天学过的，这里都能查到。

自测 8 题