# A股历史行情数据落库前的字段校验：日期格式、数值类型与空值处理

## 一、问题：解析成功，不等于可以入库

把一段 JSON 转成 Python 对象只是第一步。真正容易出事的是紧接着的那句 `INSERT`：日期字段格式不统一、同名字段在不同接口里语义不同、成交量是百万量级的浮点数、成交额是十位数量级——任何一条没提前约定好，都会在建表或批量写入时炸开，或者更糟，写进去了但精度丢了、日期错了，等到查数时才发现。

还有一个容易被误判的情形：`0` 和 `0.0` 是**有值**，不是缺失。停牌标记 `sf` 为 `0.0` 表示不停牌，成交量为 `0` 也可能是真实记录。如果校验函数写成「值为真才通过」，一整批合法数据会被当成脏数据丢掉。

本文用一次真实的日线返回，把 9 个字段的类型、取值范围和空值情况全部量一遍，然后给出一段「校验通过才落库」的完整代码，落库用内存数据库演示，不依赖任何外部服务。全文只讨论数据处理，不涉及行情判断。

## 二、先看结果：一条可以在线验证的返回

下面这条地址可以直接点开，返回的是日线数组：

https://api.mairuiapi.com/hsstock/history/000001.SZ/d/n/LICENCE-F6C7-C0C7-EF1DC61C61F9?st=20250101&et=20251231&lt=50

紧跟一句说明：`hsstock/history` 是历史分时路径，`000001.SZ` 是「股票代码.市场」，`d` 是日线级别，`n` 是不复权口径，最后一段是演示证书；`st`、`et` 是起止时间（YYYYMMDD），`lt=50` 指定取最新 50 条。本次实测返回 50 条，按交易时间升序，范围 `2025-09-15` 到 `2025-12-01`。首条的实测内容：

```json
{"t":"2025-09-15","o":11.66,"h":11.71,"l":11.58,"c":11.71,"v":1011847.0,"a":1178308953.0,"pc":11.69,"sf":0.0}
```

注意 `t` 是纯日期字符串，`v` 是带 `.0` 的浮点，`a` 是十位数量级，`sf` 是 `0.0`。这四处就是落库前必须显式处理的地方。

另外补一条实测：同一接口用 `lt=3` 请求时返回 3 条，不带 `lt` 时同一区间返回 50 条。**返回条数一律以实际响应长度为准**，不要把「请求了几条」写成校验规则里的常量。

## 三、返回字段逐项说明

对 50 条返回逐条扫描后的实测结果：

| 字段 | 类型 | 含义（接口文档定义） | 50 条最小值 | 50 条最大值 | 落库约定 |
|---|---|---|---|---|---|
| `t` | `str` | 交易时间 | — | — | 按 `%Y-%m-%d` 校验后作主键 |
| `o` | `float` | 开盘价 | `11.32` | `11.81` | `REAL` |
| `h` | `float` | 最高价 | `11.37` | `11.99` | `REAL` |
| `l` | `float` | 最低价 | `11.26` | `11.74` | `REAL` |
| `c` | `float` | 收盘价 | `11.32` | `11.85` | `REAL` |
| `v` | `float` | 成交量 | `596402.0` | `1843428.0` | `REAL`，显式声明，不按样例推断 |
| `a` | `float` | 成交额 | `680158438.0` | `2124120304.0` | `REAL`，十位数量级，避免单精度 |
| `pc` | `float` | 前收盘价 | `11.32` | `11.85` | `REAL`，与 `c` 不同义 |
| `sf` | 数值 | 停牌标记：1 停牌、0 不停牌 | `0.0` | `0.0` | `REAL`，本次 50 条全为 `0.0` |

三条从表里直接读出的约束：

1. **零值不是缺失**：`sf` 在本批 50 条里全部为 `0.0`，含义是「不停牌」。校验应检查「键存在且类型正确」，不能用 `if r["sf"]` 判断完整性。
2. **同一个 `t` 只出现一次**：实测 50 条日期无重复，适合直接作主键；但代码里仍应做一次唯一性检查，不要依赖上游保证。
3. **量级差异明显**：`a` 的最大值 `2124120304.0` 是十位数，`v` 是百万量级，列类型要显式写死，不要让存储引擎从首批数据推断。

需要说明：上表的取值范围是**这次演示返回的特征**，不是接口契约。换用自己的 licence 之后，日期范围、零值分布和数值量级都可能不同，校验规则应保持通用。

## 四、接口结构与参数

地址结构：

```text
https://api.mairuiapi.com/hsstock/history/{股票代码.市场}/{分时级别}/{除权方式}/{licence}?st=&et=&lt=
```

| 位置 | 本次取值 | 说明 |
|---|---|---|
| 股票代码.市场 | `000001.SZ` | 六位代码加市场后缀 |
| 分时级别 | `d` | 支持 `5`、`15`、`30`、`60`、`d`、`w`、`m`、`y` |
| 除权方式 | `n` | 日线以上支持 `n`、`f`、`b`、`fr`、`br`；分钟级别按文档只用 `n` |
| `st` / `et` | `20250101` / `20251231` | 起止时间，YYYYMMDD 或 YYYYMMDDhhmmss |
| `lt` | `50` | 取最新的 N 条 |

本文只用 `d` 级别，顶层是数组，每条 9 个字段。若换到分钟级别，顶层仍是数组，但 `t` 会变成 `2025-12-01 14:50:00` 这种带时分秒的形式；若某个级别在指定区间内没有记录，会返回 200 加空数组 `[]`。这类结构差异应在归一化层先处理掉，再进入本文的校验层。两层分开，校验逻辑才不用为每个级别写一遍。

## 五、代码实现：校验通过才落库

```python
import json
import sqlite3
from datetime import datetime
from urllib.request import Request, urlopen

LICENCE = "LICENCE-F6C7-C0C7-EF1DC61C61F9"
URL = ("https://api.mairuiapi.com/hsstock/history/000001.SZ/d/n/"
       + LICENCE + "?st=20250101&et=20251231&lt=50")
FIELDS = ("t", "o", "h", "l", "c", "v", "a", "pc", "sf")
NUMERIC = ("o", "h", "l", "c", "v", "a", "pc", "sf")


def fetch(url):
    req = Request(url, headers={"User-Agent": "Mozilla/5.0"})
    with urlopen(req, timeout=20) as resp:
        return json.loads(resp.read().decode("utf-8"))


def validate(rows):
    """返回问题列表；空列表表示可以落库。"""
    issues, seen = [], set()
    for i, r in enumerate(rows):
        lack = [k for k in FIELDS if k not in r]
        if lack:
            issues.append("row %d missing %s" % (i, lack))
            continue
        try:
            day = datetime.strptime(r["t"], "%Y-%m-%d").date()
        except ValueError:
            issues.append("row %d bad date %r" % (i, r["t"]))
            continue
        if day in seen:
            issues.append("row %d duplicate date %s" % (i, day))
        seen.add(day)
        # 只检查类型与键是否存在，零值合法
        for k in NUMERIC:
            if not isinstance(r[k], (int, float)):
                issues.append("row %d %s not numeric" % (i, k))
        if not (r["l"] <= r["o"] <= r["h"] and r["l"] <= r["c"] <= r["h"]):
            issues.append("row %d OHLC out of range" % i)
    return issues


rows = fetch(URL)
if not isinstance(rows, list):
    raise TypeError("expect list, got %s" % type(rows).__name__)
issues = validate(rows)

print("rows=%d fields=%d range=%s..%s" % (
    len(rows), len(rows[0]), rows[0]["t"], rows[-1]["t"]))
print("issues=%d %s" % (len(issues), issues[:3]))
print("date unique:", len({r["t"] for r in rows}) == len(rows))
print("sf values:", sorted({str(r["sf"]) for r in rows}),
      " a zero count:", sum(1 for r in rows if r["a"] == 0))
for k in NUMERIC:
    print("%-3s min=%-16s max=%s" % (
        k, min(r[k] for r in rows), max(r[k] for r in rows)))

if issues:
    raise ValueError("validation failed, abort before insert")

# 校验通过后才建表写入；主键用 t，重复导入用 REPLACE 保持幂等
con = sqlite3.connect(":memory:")
con.execute("""CREATE TABLE kline (
    t TEXT PRIMARY KEY, o REAL, h REAL, l REAL, c REAL,
    v REAL, a REAL, pc REAL, sf REAL)""")
con.executemany("INSERT OR REPLACE INTO kline VALUES (?,?,?,?,?,?,?,?,?)",
                [(r["t"], r["o"], r["h"], r["l"], r["c"], r["v"],
                  r["a"], r["pc"], r["sf"]) for r in rows])
con.commit()
print("inserted=", con.execute("SELECT COUNT(*) FROM kline").fetchone()[0],
      " min_t=", con.execute("SELECT MIN(t) FROM kline").fetchone()[0],
      " max_t=", con.execute("SELECT MAX(t) FROM kline").fetchone()[0])
```

实测运行输出（原样）：

```text
rows=50 fields=9 range=2025-09-15..2025-12-01
issues=0 []
date unique: True
sf values: ['0.0']  a zero count: 0
o   min=11.32            max=11.81
h   min=11.37            max=11.99
l   min=11.26            max=11.74
c   min=11.32            max=11.85
v   min=596402.0         max=1843428.0
a   min=680158438.0      max=2124120304.0
pc  min=11.32            max=11.85
sf  min=0.0              max=0.0
inserted= 50  min_t= 2025-09-15  max_t= 2025-12-01
```

`validate()` 的设计要点是：**先查键是否存在，再查类型，最后查业务约束**；零值全程合法。OHLC 那条检查（`l <= o <= h` 且 `l <= c <= h`）在实测 50 条上全部通过，属于便宜又有效的一道防线。只有 `issues` 为空才执行 `INSERT`，否则直接抛错，不会把半批脏数据写进库。

注意代码里 `sf` 也放在 `NUMERIC` 一起做类型检查，而不是判断 `if r["sf"] == 0` 就跳过——那正是「把零值当空值」的典型写法。

## 六、演示证书的行为说明

可以自己点开两条对照，只把股票代码从 `000001.SZ` 换成 `600519.SH`：

- https://api.mairuiapi.com/hsstock/history/000001.SZ/d/n/LICENCE-F6C7-C0C7-EF1DC61C61F9?st=20250101&et=20251231&lt=50
- https://api.mairuiapi.com/hsstock/history/600519.SH/d/n/LICENCE-F6C7-C0C7-EF1DC61C61F9?st=20250101&et=20251231&lt=50

实测两次返回**逐字节相同**：都是 50 条、范围 `2025-09-15` 到 `2025-12-01`，`o` / `h` / `l` / `c` 等数值完全一致。

示例使用的是演示证书，服务端固定返回 `000001` 的样例数据，因此替换请求中的股票代码不会改变返回结果。演示证书的作用只有两个：确认接口连通、看清返回字段结构。若需要验证其他标的的真实历史数据，需要在请求中使用自己的 licence 参数。

因此本文表中的取值范围只能用于验证**校验逻辑是否写得对**，不能当作某个标的的真实序列特征。换用自己的 licence 之后，零值字段、日期范围和数值量级都可能不同，校验规则应保持通用，不要把「`sf` 恒为 `0.0`」写成断言。

## 七、常见问题与踩坑

**把零值当空值。** `sf` 本批全为 `0.0`，`v`、`a` 在非交易记录上也可能为 0。用 `if not value` 判断会误删合法数据；正确做法是检查键与类型。

**两种时间格式混进一列。** 日线 `t` 是 `2025-09-15`，分钟级 `t` 是 `2025-12-01 14:50:00`。建议保留原始字符串一列，另存一列按级别解析后的时间，各自用对应的 `strptime` 格式校验。

**用窄类型存成交额。** 实测 `a` 最大 `2124120304.0`，是十位数量级的浮点。显式声明 `REAL` / `DECIMAL`，避免单精度丢位或被推成整型。

**不查日期唯一性就设主键。** 本批无重复，但上游合并多批数据时很可能出现重叠日期。要么先查重，要么用 `INSERT OR REPLACE` 保证幂等。

**校验失败仍继续写入。** 常见写法是把问题 `print` 出来但不中断。本文在 `issues` 非空时直接 `raise`，避免半批数据入库。

**把样例特征写成通用规则。** 「50 条」「`sf` 恒为 `0.0`」「日期范围」都是这次演示返回的特征，不是接口契约。校验只约束类型、格式和结构，不约束具体数值范围。

**逐条提交拖慢批量写入。** 本文用 `executemany` 一次性提交 50 条，实测写入无报错；批量场景应把校验与写入分成两个阶段，校验全通过后再一次性提交，失败时整个批次回滚。

**让存储引擎自己猜列类型。** 内存库演示里显式声明了 `REAL` / `TEXT`，这是有意为之：某些存储引擎会从首批数据推断类型，而本批 `sf` 全是 `0.0`，很容易被推成偏窄的类型，等后续批次出现非零值时再改表就麻烦了。

**把校验逻辑绑死在 50 条上。** 校验函数应当只遍历传入的 `rows`，不对长度、日期范围做任何硬编码；本文的 `validate()` 用 `enumerate(rows)` 逐条检查，正是为了换一批数据也能直接复用。同理，主键冲突策略要显式选择：本文用 `INSERT OR REPLACE` 保证重复导入幂等，若业务上更希望保留首次写入，就应换成 `INSERT OR IGNORE` 并把冲突记入日志。

## 八、小结与数据来源说明

一套可复用的落库前校验，只做四件事：键完整性、类型正确性、时间格式与唯一性、基本结构约束（OHLC 范围）。校验全部通过才执行写入，并用主键 + `INSERT OR REPLACE` 保持重复导入幂等。零值按合法数据处理，样例特征不写成硬编码规则。

本文所有返回样例、字段类型、取值范围与代码输出均来自对上述公开接口地址的实际请求，采集时间为 2026-11-12；字段含义以当期接口文档定义为准，落库演示使用内存数据库，不写入任何外部存储。演示返回的条数与数值是固定样例特征，不是接口契约。

本文只讨论接口返回结构与数据处理，不涉及任何行情判断或投资建议。


把一段 JSON 转成 Python 对象只是第一步。真正容易出事的是紧接着的那句 INSERT：日期字段格式不统一、同名字段在不同接口里语义不同、成交量是百万量级的浮点数、成交额是十位数量级——任何一条没提前约定好，都会在建表或批量写入时炸开，或者更糟，写进去了但精度丢了、日期错了，等到查数时才发现。

A股历史行情数据落库前的字段校验：日期格式、数值类型与空值处理

数据库

后端

A股历史行情数据落库前字段校验指南，涵盖日期格式、数值类型与空值处理。基于真实接口返回50条日线数据，详细解析t、o、h、l、c、v、a、pc、sf九个字段的校验规则。提供完整Python代码，实现键完整性、类型检查、OHLC范围验证及日期唯一性校验，通过后才执行SQLite写入。强调零值合法、类型显式声明、避免样例特征硬编码等关键要点。

数据处理

代码解释

Python

Agent

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

A股历史行情数据落库前字段校验指南，涵盖日期格式、数值类型与空值处理。基于真实接口返回50条日线数据，详细解析t、o、h、l、c、v、a、pc、sf九个字段的校验规则。提供完整Python代码，实现键完整性、类型检查、OHLC范围验证及日期唯一性校验，通过后才执行SQLite写入。强调零值合法、类型显式声明、避免样例特...

A股历史行情数据落库前的字段校验：日期格式、数值类型与空值处理-腾讯云开发者社区-腾讯云

A股历史行情数据落库前的字段校验：日期格式、数值类型与空值处理

A股历史行情数据落库前的字段校验：日期格式、数值类型与空值处理

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐