Skip to content

各省教材版本不一样,教育产品怎么按 IP 自动切换?PHP 实现与配置表 ​

有个做小学口算训练的团队找过来,问题听起来很小:注册页有个"教材版本"下拉框,默认选中人教版,结果后台数据显示,河南、山东、江苏三地的用户里,将近四成在注册后一周内手动改过版本,改完的题量是没改的三倍。没改的那批人,很多是直接流失了——打开发现题目跟课本对不上,家长第一反应是"这软件不行"。

他们的下拉框有十一个选项,让一个三年级家长自己判断孩子用的是哪个版本,本来就是件不讲理的事。课本封面有出版社名字,但家长记不住;同一个市,语文和数学的版本还可能不一样。

所以这事真正的解法不是把下拉框做漂亮,是先替用户选对,再允许他改。而知情信息里最便宜的那个,是 IP 归属地。

一、教材版本的"碎",碎在学科而不是碎在省 ​

动手之前得先搞清楚一件事:不是所有学科都需要按地区切。

义务教育阶段的语文、历史、道德与法治,从 2017 年起分三年统一换成了统编教材(人教社出版),全国一套,没有地区差异。这三科你要做地区映射,纯属给自己找麻烦。

真正分版本的是数学、英语、科学、音乐、美术这些。数学最典型:人教、北师大、苏教、沪教、青岛、西师、冀教、浙教、湘教……一个省用哪套,跟当地的教研传统、早年的课改实验区有关。

碎到什么程度?举几个常见的:

  • 江苏数学主流是苏教版,但省内部分城市用北师大版或人教版;
  • 山东数学常见青岛版,也有地市用人教版;
  • 北京数学,不同区用人教版和北师大版都有;
  • 上海是独立体系,沪教版,跟全国都不接;
  • 重庆数学常见西师版。

再往下还有年级差异:同一学科,一二年级和五六年级版本可能不同(尤其是英语起点年级)。

这意味着两件事:一是配置表必须做到「学科 × 地区」两级,不能只按省;二是任何自动判断都只能是默认值,必须能被用户覆盖。指望靠一个省名把版本猜准,是不现实的。

二、方案:四级优先,把"猜"标出来 ​

解析顺序定成这样,从上到下:

  1. 用户自己选的——最高优先级,只要他选过,永远不再用 IP 覆盖;
  2. 城市级配置——计划单列市、教材改革试点市,单独配(深圳的英语、青岛的数学、大连的数学都属于这类);
  3. 省级默认——省里大多数地市的版本;
  4. 兜底——人教版,同时把结果标记成 default,前端提示"请确认孩子的教材版本"。

关键是第 4 步的 source 字段。它决定了前端怎么展示:

source前端表现
user保持用户选择,不提示
city / province显示"已按你所在地区预选:苏教版(数学)",旁边一个小链接「不对?改一下」
default不做预选,直接把下拉框展开,文案改成"请选择孩子的教材版本"

这个区分很重要。default 状态下如果也显示"已按你所在地区预选",等于在撒谎,用户改选率反而更高。

三、PHP 实现 ​

代码分三块:取真实 IP、查归属地(带文件缓存和限速)、按配置表解析。跑在 PHP 8 上,只依赖 curl。

php
<?php
declare(strict_types=1);

const IP9_API = 'https://ip9.com.cn/get';
const CACHE_TTL = 86400; // 归属地一天查一次足够

// 版本字典:code => 展示名,运营在后台维护
const EDITIONS = [
    'pep' => '人教版', 'bsd' => '北师大版', 'sj' => '苏教版',
    'sh'  => '沪教版', 'yj'  => '粤教版',   'zj' => '浙教版',
    'xj'  => '湘教版', 'hb'  => '冀教版',   'qd' => '青岛版',
    'xs'  => '西师版', 'wys' => '外研版',
];

// 省级默认值:只对"分版本"的学科配,语文/历史/道法不用配
const PROVINCE_DEFAULT = [
    '北京' => ['math' => 'bsd', 'chinese' => 'pep', 'english' => 'pep'],
    '上海' => ['math' => 'sh',  'chinese' => 'sh',  'english' => 'sh'],
    '江苏' => ['math' => 'sj',  'chinese' => 'pep', 'english' => 'yj'],
    '浙江' => ['math' => 'zj',  'chinese' => 'pep', 'english' => 'pep'],
    '广东' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'yj'],
    '山东' => ['math' => 'qd',  'chinese' => 'pep', 'english' => 'pep'],
    '河北' => ['math' => 'hb',  'chinese' => 'pep', 'english' => 'pep'],
    '湖南' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'xj'],
    '重庆' => ['math' => 'xs',  'chinese' => 'pep', 'english' => 'pep'],
    '四川' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'pep'],
];

// 城市级覆盖:key 用接口返回的 city_code(小写拼音),比中文城市名稳
const CITY_OVERRIDE = [
    'shenzhen' => ['english' => 'yj'],
    'qingdao'  => ['math' => 'qd'],
    'dalian'   => ['math' => 'bsd'],
];

final class TextbookResolver
{
    private string $cacheDir;
    private float $lastCallAt = 0.0;

    public function __construct(string $cacheDir)
    {
        $this->cacheDir = rtrim($cacheDir, '/');
        if (!is_dir($this->cacheDir)) {
            mkdir($this->cacheDir, 0775, true);
        }
    }

    /** 取客户端 IP:XFF 只取首段,内网和保留地址返回 null。 */
    public static function clientIp(array $server): ?string
    {
        $raw = $server['HTTP_X_FORWARDED_FOR'] ?? $server['REMOTE_ADDR'] ?? '';
        $ip = trim(explode(',', $raw)[0]);
        if (str_starts_with($ip, '::ffff:')) {
            $ip = substr($ip, 7); // IPv4-mapped IPv6
        }
        if ($ip === '' || filter_var($ip, FILTER_VALIDATE_IP,
                FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
            return null;
        }
        return $ip;
    }

    /** 查归属地:文件缓存 24 小时,429 退避一次,非法 IP 直接放弃。 */
    public function geo(string $ip): ?array
    {
        $file = $this->cacheDir . '/' . md5($ip) . '.json';
        if (is_file($file) && time() - filemtime($file) < CACHE_TTL) {
            $cached = json_decode((string) file_get_contents($file), true);
            if (is_array($cached)) {
                return $cached;
            }
        }

        // 免费版 60 次/分钟,相邻请求留 1.05 秒间隔
        $wait = 1.05 - (microtime(true) - $this->lastCallAt);
        if ($wait > 0) {
            usleep((int) ($wait * 1_000_000));
        }
        $this->lastCallAt = microtime(true);

        $url = IP9_API . '?ip=' . urlencode($ip);
        for ($try = 0; $try < 2; $try++) {
            $ch = curl_init($url);
            curl_setopt_array($ch, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_CONNECTTIMEOUT => 2,
                CURLOPT_TIMEOUT        => 3,
            ]);
            $body = curl_exec($ch);
            $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
            curl_close($ch);

            if ($code === 429) {
                usleep(1_000_000);
                continue;
            }
            if ($body === false || $code !== 200) {
                return null;
            }
            $json = json_decode($body, true);
            if (!is_array($json) || ($json['ret'] ?? 0) !== 200) {
                return null;
            }
            $data = $json['data'];
            file_put_contents($file, json_encode($data));
            return $data;
        }
        return null;
    }

    /**
     * $userChoice 有值就直接用,IP 只做默认值,永远不覆盖手动选择。
     */
    public function resolve(?string $ip, string $subject = 'math', ?string $userChoice = null): array
    {
        if ($userChoice !== null && isset(EDITIONS[$userChoice])) {
            return ['edition' => $userChoice, 'name' => EDITIONS[$userChoice],
                    'source' => 'user', 'province' => null, 'city' => null];
        }

        $geo  = $ip ? $this->geo($ip) : null;
        $prov = $geo['prov'] ?? '';
        $city = $geo['city'] ?? '';
        $cityKey = $geo['city_code'] ?? '';

        $edition = null;
        $source  = 'default';

        if ($cityKey !== '' && isset(CITY_OVERRIDE[$cityKey][$subject])) {
            $edition = CITY_OVERRIDE[$cityKey][$subject];
            $source  = 'city';
        } elseif ($prov !== '' && isset(PROVINCE_DEFAULT[$prov][$subject])) {
            $edition = PROVINCE_DEFAULT[$prov][$subject];
            $source  = 'province';
        }
        $edition = $edition ?? 'pep'; // 兜底,但一定要标出来

        return ['edition' => $edition, 'name' => EDITIONS[$edition] ?? $edition,
                'source' => $source, 'province' => $prov, 'city' => $city];
    }
}

命令行跑一遍,接口是真实调用的:

IP                   | 省  | 市  | 数学默认 | 来源   | 说明
202.96.209.133       | 上海 | 上海 | 沪教版 | province |
202.96.128.86        | 广东 | 广州 | 人教版 | province |
202.102.128.68       | 山东 | 济南 | 青岛版 | province |
219.141.136.10       | 北京 | 北京 | 北师大版 | province |
61.139.2.69          | 四川 | 成都 | 人教版 | province |
2408:8000:1100::1    | 北京 | 北京 | 北师大版 | province |
1.1.1.1              | -    | -    | 人教版 | default  | 未命中,兜底需引导用户手选

三个细节值得说:

IPv6 是同一套逻辑。 2408:8000:1100::1 返回「北京 / 北京 / 中国联通城域网」,跟 IPv4 结果一致,不用为移动网络单独写分支。早期很多教育产品只处理了 IPv4,结果安卓移动端用户全都落到 default,改选率高得离谱,还查不出原因。

city_code 比中文城市名稳。 接口返回的 city_code 是小写拼音(hangzhou、shenzhen),拿它做覆盖表的 key,不会被"市/地区/自治州"这类后缀差异坑到。

境外 IP 一定落到 default。 1.1.1.1 是澳大利亚,prov 和 city 都是空。海外华人子女、国际学校用户确实存在,但教材体系跟国内完全不同,这时候正确做法是让用户自己选或者选课程体系,不是硬猜一个「人教版」。

四、真正有用的那一步:用"改选率"反过来修配置 ​

配置表刚上线一定不准。别指望运营拍脑袋拍对,让数据说话:

给每次「用户手动改选版本」打一条埋点,带上服务端算出来的省份和改选前的默认值。按省聚合,算两个指标:

  • 改选率 = 改选人数 / 该省曝光人数;
  • 流向 = 改选后集中去了哪个版本。

如果一个省的改选率明显高于全国均值(比如全国 12%,某省 45%),而且改选后的流向高度集中(八成流向人教版),那基本可以断定:这个省的默认配置配错了。把配置改掉,两周后再看改选率有没有掉下来。

这套闭环比任何"权威教材版本对照表"都可靠——因为对照表会过时(教材三五年一换),而你的用户每天都在给你标注正确答案。

顺带说,曝光埋点里不要存完整 IP。存省份、城市和 source 就够了,IP 用完即弃。这既是《个人信息保护法》里最小必要原则的要求,也省掉一堆存储和脱敏的麻烦——你需要的粒度本来就是省,不是个人。

五、几个会翻车的地方 ​

VPN 和公司网络会让默认值偏。 家长在公司加班时给孩子注册,出口 IP 是公司总部所在地(很多集团总部在北京、上海)。这类用户占比不高但投诉很响,所以那个「不对?改一下」的入口必须在首屏可见,不能藏在设置里。

双城家庭。 户籍在河南、在江苏上学,或者反过来。IP 只能判断"现在在哪里上网",判断不了"在哪里上学"。所以配置表再准,也要留手动入口。

别把映射表写进前端包。 见过把十一个版本和省份映射硬编码在小程序里的,教材一改版就得重新提审发版,两周才能上线。这张表放服务端,前端只拿结果。

学科粒度要一开始就留出来。 如果表结构是 省 => 版本,后面加英语版本时会想哭。哪怕暂时只有数学,也写成 省 => {学科: 版本}。

缓存别只放进程内。 PHP-FPM 每个 worker 的进程内缓存互相看不见,热 IP 会被重复查;文件缓存或 Redis 都行,key 用 IP,TTL 一天。免费版 60 次/分钟的限制,配上一天缓存,日活一两万的产品基本碰不到上限。

总结 ​

这件事的技术含量不高,思路值钱:IP 归属地给出一个"大概率对"的默认值,source 字段诚实地告诉前端这个值有多可信,用户的每一次改选都变成修配置的依据。

接口就是 https://ip9.com.cn/get?ip=<ip>,返回 prov、city、city_code 这些字段,IPv4/IPv6 都支持,不传 ip 查当前请求方,免费版 60 次/分钟、不用注册。要区县级精度或者 ip_type 区分家宽/机房,那是 VIP 版的能力,教材场景一般用不上——省级加城市级覆盖已经够。

最后提醒一句:教材版本以当地教育局和学校实际用书为准,任何配置表都只是默认值。把这个预期写进产品文案里,比多配十个省都管用。