第23章 检索邮政编码

来源、版次与运行边界

“第23章 检索邮政编码”以作者维护的第 5 版支持页核定 2016 年 3 月 12 日首刷、两位作者、松本行弘监修以及四部分 23 章目录；逐章程序清单、练习答案和勘误只作为公开支持材料，不被冒充为原书全文。

对“第23章 检索邮政编码”而言，中文解释、示例、交互、练习和答案均为独立教学重写；站内中文章名是与官方 23 章顺序对应的课程映射，不宣称是日文小节的逐字翻译，也不从公开程序清单复制整段实现。

“第23章 检索邮政编码”固定在 Ruby 2.3 语境；Ruby 2.3.0 官方文档与稳定版发布说明用于核对当时可用的语言和标准库行为。现代 Ruby 的差异只能另列迁移说明，不能静默改变本页示例的版本结论。

围绕“怎样从邮政编码原始数据重建可验证、可切换、可回滚的查询索引？”，本页验收“第23章 检索邮政编码的输入样本、接收者与方法、关键状态前后值、正常与失败输出、异常或退出状态，以及复位后的再次运行记录。”。先预测正常轨迹，再只注入“直接向在线数据库逐行写入，失败时暴露半完成数据集”；若无法定位第一处状态分岔，就拒绝当前解释。

从“CSV导入数据库后select”开始扩展

可维护检索工具需要可追溯source、strict parsing、schema version、atomic rebuild、query contract与可重复verification。让结果可解释。

先预测：导入到一半进程崩溃，reader会看到半张表吗？若直接清空live table逐行insert，会；正确做法是在transaction/新database中完整构建、validate后一次切换。

获取邮政编码

原书使用日本邮政编码数据。实现应从官方versioned source获取，记录URL、download timestamp、license、content length与cryptographic checksum；限制timeout/redirect/max bytes。支持重建和审计。

require "digest"
 
raw = File.binread(source_path)
metadata = {
  source_path: source_path,
  bytes: raw.bytesize,
  sha256: Digest::SHA256.hexdigest(raw),
}
p metadata

Raw archive/CSV不可覆盖同名无版本文件；使用content hash/version目录。Network acquisition与import分开，测试可用固定fixture，offline rebuild仍有证据。

csv库

CSV允许quoted commas、embedded newlines与escaped quotes，不能String#split。Ruby csv库逐row解析并可设置encoding/header。先于field normalization。

require "csv"
 
CSV.foreach(csv_path, encoding: "Windows-31J:UTF-8") do |row|
  raise "unexpected column count" unless row.length == EXPECTED_COLUMNS
 
  source_id = row.fetch(0)
  postal_code = row.fetch(2)
  prefecture = row.fetch(6)
  city = row.fetch(7)
  locality = row.fetch(8)
  # Validate and emit a normalized record.
end

实际column mapping按数据版本官方schema固定；示例index仅展示方法。Decode invalid row时保存row number/byte locator与raw quarantine，不silent replace关键code/name。Quoted multiline会让physical line与CSV row不同，使用parser提供locator。

Normalization保留original display fields，并生成canonical postal digits、Unicode normalization/case/search key。避免不可逆覆盖原文。

sqlite3库

SQLite是embedded transactional database；Ruby使用sqlite3 gem，需要在Gemfile/lock固定版本及native dependency。不只require "sqlite3"。

require "sqlite3"
 
database = SQLite3::Database.new(database_path)
database.execute_batch <<~SQL
  CREATE TABLE postal_codes (
    source_id TEXT NOT NULL,
    postal_code TEXT NOT NULL,
    prefecture TEXT NOT NULL,
    city TEXT NOT NULL,
    locality TEXT NOT NULL,
    search_key TEXT NOT NULL
  );
  CREATE INDEX postal_codes_postal_idx ON postal_codes(postal_code);
  CREATE INDEX postal_codes_search_idx ON postal_codes(search_key);
SQL

Postal code不一定是单行唯一，schema不要想当然UNIQUE；source record key/version决定identity。Index由query pattern驱动，使用EXPLAIN QUERY PLAN与realistic benchmark验证，过多index拖慢import并增文件。

插入数据

Bulk import在一个transaction中使用prepared statement，逐row bind values；不要字符串拼SQL。避免partial live state。

database.transaction
statement = database.prepare <<~SQL
  INSERT INTO postal_codes
    (source_id, postal_code, prefecture, city, locality, search_key)
  VALUES (?, ?, ?, ?, ?, ?)
SQL
 
begin
  records.each do |record|
    statement.execute(
      record.fetch(:source_id),
      record.fetch(:postal_code),
      record.fetch(:prefecture),
      record.fetch(:city),
      record.fetch(:locality),
      record.fetch(:search_key),
    )
  end
  database.commit
rescue
  database.rollback
  raise
ensure
  statement.close if statement
end

Ruby/sqlite3 transaction API细节按locked version验证；block-form transaction更可靠。Performance设置pragmas前理解durability，candidate DB可调import mode但activation前integrity_check/close/fsync policy明确。

导入后验证与原子激活

Validate row counts、required fields、duplicate distribution、sample exact queries、SQLite integrity_check、source metadata和schema version。。

Build到same filesystem temp DB，close/flush后atomic rename/symlink pointer swap；reader connection lifecycle决定何时打开新版本。保留previous version用于rollback与retention。

检索数据

Query input先normalize/validate，SQL values用placeholders。。

def find_by_postal_code(database, input, limit: 20)
  digits = input.to_s.gsub(/\D/, "")
  raise ArgumentError, "postal code must contain 7 digits" unless /\A\d{7}\z/.match(digits)
 
  database.execute(<<~SQL, digits, limit)
    SELECT postal_code, prefecture, city, locality
    FROM postal_codes
    WHERE postal_code = ?
    ORDER BY prefecture, city, locality
    LIMIT ?
  SQL
end

SQL placeholder是否可用于LIMIT由driver/version验证；必要时严格Integer cap后安全构造固定位置。Identifiers/order columns不能用value placeholders，必须allowlist。No rows是正常empty result，不rescue成database error。

前缀与地名检索

Prefix search需escape LIKE %/_或用range query；name search受Unicode normalization、tokenization和ranking，可能用FTS extension/normalized index。防全表/无限结果。

Stable ORDER BY包含tie-breaker，pagination使用keyset或明确offset consistency。Result带source version，让用户/日志知道基于哪个dataset。

小结：从Raw data到可解释结果

端到端验收保存source metadata、raw hash、normalization/schema version、import report、integrity result、query contract和active DB id。完成项目闭环。

CLI normal output输出rows/JSON，stderr输出diagnostics，status区分found/not-found/invalid/system failure。Tests使用small fixture覆盖quoted CSV、多行、invalid encoding、duplicates、transaction rollback、index plan和deterministic query。

正式节点与章专属证据

• 获取邮政编码 ：第 1 个正式节点要能回到“原始数据、模式、事务导入、完整性检查和活动版本形成闭环。”，并说明故障发生前后的第一处差异。
• csv库 ：第 2 个正式节点要能回到“原始数据、模式、事务导入、完整性检查和活动版本形成闭环。”，并说明故障发生前后的第一处差异。
• sqlite3库 ：第 3 个正式节点要能回到“原始数据、模式、事务导入、完整性检查和活动版本形成闭环。”，并说明故障发生前后的第一处差异。
• 插入数据 ：第 4 个正式节点要能回到“原始数据、模式、事务导入、完整性检查和活动版本形成闭环。”，并说明故障发生前后的第一处差异。
• 检索数据 ：第 5 个正式节点要能回到“原始数据、模式、事务导入、完整性检查和活动版本形成闭环。”，并说明故障发生前后的第一处差异。

本章回顾：数据库只是可重建索引，不是来源本身

1. Official raw dataset版本化保存hash/license/encoding，CSV用parser和严格row schema。
2. Original display fields与normalized lookup fields并存，normalization独立version。
3. SQLite schema/index由query contract驱动，gem/pragmas/schema version固定。
4. Candidate在transaction中prepared bulk import，验证后原子activate，old version可rollback。
5. Query参数化values、allowlist identifiers、限制/稳定排序并保留dataset provenance。

练习与答案

名词解释