kleague-results 使用指南基于官方 K League JSON 端点的 Node.js 赛果与积分榜客户端【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南围绕仓库中的 kleague-results 包 展开它是一个封装韩国职业足球联赛K리그官方 JSON 接口的可复用 Node.js 客户端可同时按日期查询比赛结果与当前积分榜。读完本文你将掌握该包的安装方式、三个核心 APIgetMatchResults/getStandings/getKLeagueSummary的参数与返回值结构并能结合 源码实现 与 测试用例 理解其日期过滤、球队别名匹配、状态归一化等底层原理。为什么用官方 JSON 端点而不是 HTML 爬虫K리그 官方站点的比赛数据是动态页面传统做法是抓取 HTML 后解析 DOM。该包选择直接请求官方 JSON 接口维护成本显著低于 HTML 爬虫——只要官方接口的响应结构不变客户端就不需要频繁适配页面改版。包内硬编码了两个官方数据表面数据内容端点请求方式赛程 / 比赛结果https://www.kleague.com/getScheduleList.doPOST按月请求球队积分榜https://www.kleague.com/record/teamRank.doPOST携带 query 参数这两个 URL 在 src/index.js 中定义为常量测试用例也通过构造相同的端点来模拟请求见 test/index.test.js。安装与运行环境包要求Node.js 18在 package.json 的engines字段中声明因为实现依赖原生global.fetch。安装方式npm install kleague-results如果你要在 Agent / CLI 场景中直接使用可以全局安装npm install -g kleague-results该包是 k-skill 仓库中 kleague-results 技能 的数据层技能文档建议在全局 Node 包缺失时先安装kleague-results而不是用 HTML 抓取绕过见 instruction.md。快速上手下面是最小可用示例同时演示了三个 API 的调用方式摘自包 READMEconst { getKLeagueSummary, getMatchResults, getStandings } require(kleague-results); (async () { const results await getMatchResults(2026-03-22, { leagueId: K리그1, team: FC서울, }); const standings await getStandings({ leagueId: 1, year: 2026, }); const summary await getKLeagueSummary(2026-03-22, { leagueId: K리그1, team: FC서울, includeStandings: true, }); console.log(results.matches[0]); console.log(standings.rows[0]); console.log(summary); })();从 package.json 可以看出该包的main入口是src/index.js发布时仅包含src目录和README.md也就是说你安装后引入的正是下面将要分析的源码。API 详解包对外暴露三个主要异步函数另有两个底层请求函数fetchScheduleMonth/fetchStandings供高级复用见 src/index.js 的导出列表。getMatchResults(date, options)按日期查询某一联赛的比赛结果可选按球队过滤。dateYYYY-MM-DD字符串或Date对象options.leagueId1、2、K리그1、K리그2也接受K1、KLEAGUE1、K2、KLEAGUE2等别名options.team球队简称 / 全名 / 球队代码别名例如서울、FC서울、K09返回对象包含queryDate、leagueId、filteredTeam指定球队时的归一化结果、clubs参赛球队目录和matches规范化后的比赛数组。getStandings(options)查询当前积分榜。options.leagueId1或2options.year赛季年份默认取韩国时区Asia/Seoul的当前年份。该默认值由源码中的getCurrentKoreaYear()实现使用Intl.DateTimeFormat并指定timeZone: Asia/Seoul见 src/index.js返回对象包含leagueId、year、isSplitRank、notice和rows积分榜行数组。getKLeagueSummary(date, options)一次调用同时返回「某日比赛结果 当前积分榜」是 Agent 场景下最常用的组合接口。options与getMatchResults相同额外支持includeStandings默认true源码中判断条件为options.includeStandings ! false见 src/index.js。其组合逻辑是先取比赛结果再以查询日期中的年份为赛季年份调用积分榜matches.queryDate.slice(0, 4)并把比赛中出现的球队目录传给积分榜解析从而保证两边球队名称一致见 src/index.js。参数归一化别名、日期与时区leagueId 的别名解析normalizeLeagueId维护了一张别名映射表见 src/parse.js规范化结果接受的别名1K리그11、K1、KLEAGUE1、K리그12K리그22、K2、KLEAGUE2、K리그2解析前会先做normalizeToken处理NFKC 归一化、转大写、剔除除字母数字与韩文外的字符。因此k league 2也能被解析为2测试用例 index.test.js 验证了这一点。传入K리그3等无法解析的值会抛出leagueId must resolve to K League 1 or 2错误空值则默认回退到1。date 的解析与校验normalizeDateInput支持YYYY-MM-DD和YYYY.MM.DD两种字符串格式也接受Date对象Date对象会按Asia/Seoul时区格式化为日期部分避免时区偏移导致日期串位。字符串格式会经过严格的日历校验含闰年判断2026-13-40这类不存在的日期在发起任何网络请求之前就会被拒绝——测试 index.test.js 专门验证了这一点断言fetchCalled为false。team 的别名匹配buildClubDirectory从响应中的clubList构建球队目录为每支球队收集teamId如K09、简称서울、全名FC서울等所有字段作为别名 token。resolveTeamQuery会用同样的 token 规范化方式匹配用户输入因此서울、FC서울、K09都能命中同一支球队。注意서울这类短名在 K리그2 中可能对应서울 이랜드技能文档明确提示了这种歧义见 instruction.md 的 Failure modes 一节。数据规范化原始 JSON 如何变成结构化对象官方接口返回的是面向展示的原始 JSON可在 fixtures 中查看真实响应样本包在src/parse.js中将其转换为便于程序消费的结构。比赛状态映射normalizeMatchStatus将官方状态码映射为统一语义见 src/parse.js状态码statelabelFEfinished종료已结束NSscheduled예정未开始LIVE/INlive진행 중进行中HThalftime하프타임中场休息PPpostponed연기延期CANcancelled취소取消比赛对象字段每场比赛被规范化为如下结构见normalizeScheduleItemsrc/parse.jsleagueId、competitionName如하나은행 K리그1 2026、round、gameIddate转为2026-03-22格式、dateLabel、kickOffstatus上述状态对象homeTeam/awayTeam{ code, name, fullName, homepage, leagueId }score{ home, away }未开赛时返回nullwinner仅在已结束时返回home/away/draw由determineWinner计算venue{ shortName, name }如서울 월드컵 경기장audience、broadcastChannels用//或|拆分的转播频道数组matchCenterUrl由gameId与meetSeq拼接的官方比赛中心链接测试 index.test.js 用 2026-03-22 的 fixture 验证了完整映射FC서울 主场 5:0 胜 광주、第 5 轮、状态FE/종료。积分榜行对象normalizeStandingsResponse将官方teamRank数组规范化为见 src/parse.jsrank、team含 code / name / fullNamepoints积分、played场次、win/draw/loss胜/平/负goalsFor/goalsAgainst/goalDifference进/失/净胜球form最近 6 场走势数组game01game06值为승/무/패homepage、stadium此外会按rank升序、同分按积分降序、再按韩文队名排序并用teamId去重。测试断言 2026 赛季 K리그1 有 12 行서울 以 12 分居首、4 战全胜见 index.test.js。底层请求细节src/index.js中的requestJson统一处理 HTTP 调用默认请求头包含accept-language: ko-KR以锁定韩文数据、user-agent: k-skill/kleague-results并透传signalAbortSignal与可替换的fetchImpl便于测试注入 mock。两个端点的请求方式不同值得注意赛程接口POSTbody 为{ year, month, leagueId }其中month会补零成两位如03。由于该接口按月返回数据包必须在客户端再次按请求日期精确过滤——测试用例专门断言了请求体包含month:03见 index.test.js。积分榜接口POSTquery 参数为leagueId、year、stadiumall、recordTyperank。stadiumall表示当前为全主场口径的积分榜包 README 的 Notes 部分对此有明确说明。getMatchResults内部通过fetchScheduleMonth拿整月数据再用normalizeScheduleResponse过滤出指定日期getKLeagueSummary则在其上叠加积分榜调用测试验证了组合调用时getScheduleList.do会被请求两次一次在getMatchResults一次在getKLeagueSummary内部见 index.test.js。在 Agent / CLI 场景中的实际用法该包是 k-skill 生态中 K리그 技能的数据层。技能工作流见 instruction.md 与 docs/features/kleague-results.md建议检查npm root -g下是否存在kleague-results缺失则npm install -g kleague-results不要用 HTML 抓取绕过调用getKLeagueSummary一次拿到比赛与排名将原始 JSON 整理为人类可读结果主客队、开赛时间 / 是否已结束、比分、当前排名若指定球队则只保留该队比赛保持回答紧凑scoreboard 请求先给逐场一行摘要单队请求先给该队比赛与当前排名。在非包安装环境下可用下面这种方式直接从全局 npm 目录加载模块来自 docs/features/kleague-results.md 的示例GLOBAL_NPM_ROOT$(npm root -g) node --input-typemodule - JS import path from node:path; import { pathToFileURL } from node:url; const entry pathToFileURL( path.join(process.env.GLOBAL_NPM_ROOT, kleague-results, src, index.js), ).href; const { getKLeagueSummary } await import(entry); const summary await getKLeagueSummary(2026-03-22, { leagueId: K리그1, team: FC서울, includeStandings: true, }); console.log(JSON.stringify(summary, null, 2)); JS边界情况与失败模式综合包 README 的 Notes 与技能文档的 Failure modes使用中需要注意getScheduleList.do是月粒度接口必须依赖库内按日过滤不要假设返回即当日数据查询日期在比赛开始之前时返回的是예정scheduled或진행 중live状态score与winner为null서울这类短名跨联赛存在歧义K리그2 场景下应确认是否指서울 이랜드官方接口若改变getScheduleList.do/teamRank.do的响应结构则需要更新包内的解析逻辑src/parse.js 是主要维护点日期参数在请求前即被严格校验非法日历日期不会触发网络请求。本地验证方式该包自带基于node:test的测试覆盖了联赛别名解析、日期过滤、球队别名匹配、状态映射、积分榜结构以及「mock fetch 下的三 API 组合调用」等场景见 packages/kleague-results/test/index.test.js。测试依赖两份真实响应快照schedule-kleague1-2026-03.json2026 年 3 月 K리그1 赛程与俱乐部列表和 standings-kleague1-2026.json2026 赛季 K리그1 积分榜。在包目录下执行即可运行npm test代码风格检查则通过node --check对三个 JS 文件做语法校验npm run lint见 package.json。总结kleague-results 是一个「官方 JSON 端点 客户端归一化」的典型封装对外提供三个语义清晰的异步 API对内完成 leagueId 别名归一化、韩国时区日期解析、球队别名匹配、比赛/积分榜结构标准化。它规避了 HTML 爬虫的脆弱性并把「月粒度数据按日过滤」「stadiumall积分榜」等官方接口特性封装成对调用方透明的能力。若你要在 Node.js 应用中集成 K리그 数据或为 Agent 构建韩国体育信息查询能力可直接参考本包 README、源码 与 测试 作为起点。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考