refactor(契约): 语言与判题产物的形状收进契约,学生端高频响应接上运行时校验
Some checks failed
Deploy / deploy (push) Has been cancelled

契约在前端一直只当类型包用:45 处引用里几乎全是 import type,三个 .parse() 后面
还都紧跟一个 as 把校验结果断言回去,等于没校验。这一轮把形状的来源收拢。

## 语言:三份真相并成一份

前端 utils/types.ts 手写了一份 9 值的语言联合,后端 judge/languages.ts 有自己的一套,
生产库又有一套。手抄那份**漏了 SQL**,而生产库 961 道题里有 9 道 SQL 题、
124191 条提交里有 91 条 SQL 提交 —— 这些提交的 language 在前端类型上是 undefined。
现在唯一来源是契约的 problemLanguageSchema,constants.ts 的显示映射以它为键,
契约里加语言而那边没补映射会当场编译不过。

## 判题产物:按生产数据实测收紧

judgeInfoSchema / statisticInfoSchema 的形状来自 124191 条提交的实测,不是手抄:

- info.data 有 12048 条是 null(编译失败等没有逐测试点结果),前端手抄的 Info
  却把 data 写成非空数组 —— 这 12048 条在类型上根本不成立;
- info 还允许**空对象**:非管理员看提交详情时后端下发 info: {}(权限投影)。
  收紧时必须把它算进去,否则每条非管理员看的提交详情直接 500 —— 本地实测复现过;
- statistic_info 的五个键按出现次数定成全部可选;另有 8916 条 JSONB 原文因内嵌
  带转义的 shell 输出不是合法 JSON,被后端 objectValue() 兜成 { value: ... },
  所以不能用严格对象,否则这 8916 条会被误判成分歧。

## 运行时闸门

新增 utils/contract.ts:safeParse 失败时记一条分歧(去重、控制台可见、
window.__OJ2_CONTRACT_DRIFT__ 可查)后**放行原始数据**,不白屏 —— 面向学生的
生产站点,字段空着比整页崩掉可接受。接在 7 条高频链路上:/site、/site/online、
/problems、/problems/:id、/submissions、/submissions/:id、/me。

提交详情的 info 是联合类型,调用方不再直接取 .data,统一走
utils/functions.ts 的 submissionCaseResults()。

## 验证

- vue-tsc 与 tsc -p apps/api 均 exit 0;vite build 通过;
- 契约 schema 直跑真实接口:7/7 通过(自包含脚本,从登录到详情全链路);
- 用生产备份复核收紧后的约束:961 题的 languages 无越界值,template 只出现
  C/Python3 两个键 —— 不会因为这次收紧在生产上抛错。
This commit is contained in:
2026-09-10 04:19:41 -06:00
parent a475cac128
commit aab0404ed7
11 changed files with 414 additions and 115 deletions

View File

@@ -16,7 +16,6 @@ import {
type ProblemAuthor,
type ProblemListItem,
type YearlyAc,
type ProblemList,
type CreateFlowchartResponse,
type FlowchartCurrent,
type FlowchartDetail,
@@ -34,12 +33,17 @@ import {
type ProblemSetProgressList,
type UserBadge,
problemDetailSchema,
problemListSchema,
submissionDetailSchema,
submissionListSchema,
onlineCountSchema,
websiteConfigSchema,
type FlowchartStatistics,
type SubmissionStatistics,
type SubmissionStatisticsItems,
} from "@oj2/contract"
import api from "utils/api"
import { contract } from "utils/contract"
import { filterResult } from "oj/transforms"
import type {
Announcement,
@@ -47,16 +51,12 @@ import type {
ContestRank,
Profile,
Message,
SubmissionListItem,
Exercise,
Problem,
ReactionKey,
ReactionState,
Submission,
SubmissionListPayload,
SubmitCodePayload,
OnlineCount,
WebsiteConfig,
Tutorial,
TutorialProgress,
} from "utils/types"
@@ -64,18 +64,33 @@ import type {
/**
* 题目详情。走契约的 zod 解析,形状即契约 —— 之前这里手抄了一份 camel→snake 的
* 键名映射,抄漏一个字段就是静默 undefined。
*
* 走 `contract()` 而不是裸 `parse()`:这里原来是
* `problemDetailSchema.parse(value) as Problem` —— `as` 把校验结果又断言回本地
* 类型,等于校验白做。契约现在把 `languages` / `template` 都收进了联合,
* `Problem` 不再需要额外窄化,`as` 也就没有存在的理由了。
*/
function detailProblem(value: unknown): Problem {
return problemDetailSchema.parse(value) as Problem
return contract("GET /problems/:id", problemDetailSchema, value)
}
export function getWebsiteConfig() {
return api.get<WebsiteConfig>("site")
export async function getWebsiteConfig() {
const endpoint = "site"
return contract(
"GET /site",
websiteConfigSchema,
await api.get<unknown>(endpoint),
)
}
/** 当前在线人数。只有聚合数字,「谁在线」在榜单接口里、且只对老师下发 */
export function getOnlineCount() {
return api.get<OnlineCount>("site/online")
export async function getOnlineCount() {
const endpoint = "site/online"
return contract(
"GET /site/online",
onlineCountSchema,
await api.get<unknown>(endpoint),
)
}
export async function getProblemList(
@@ -83,9 +98,14 @@ export async function getProblemList(
limit = 10,
searchParams: Record<string, unknown> = {},
) {
const res = await api.get<ProblemList>("problems", {
params: { paging: true, offset, limit, ...searchParams },
})
const endpoint = "problems"
const res = contract(
"GET /problems",
problemListSchema,
await api.get<unknown>(endpoint, {
params: { paging: true, offset, limit, ...searchParams },
}),
)
return {
results: res.results.map(filterResult),
total: res.total,
@@ -111,10 +131,12 @@ export function getProblemBeatRate(problemID: number) {
}
export async function getSubmission(id: string) {
const response = await api.get<unknown>(
`submissions/${encodeURIComponent(id)}`,
const endpoint = `submissions/${encodeURIComponent(id)}`
return contract(
"GET /submissions/:id",
submissionDetailSchema,
await api.get<unknown>(endpoint),
)
return submissionDetailSchema.parse(response) as Submission
}
export function submitCode(data: SubmitCodePayload) {
@@ -138,12 +160,27 @@ export function getSubmissions(params: Partial<SubmissionListPayload>) {
const endpoint = params.contestId
? `contests/${encodeURIComponent(params.contestId)}/submissions`
: "submissions"
// 契约里 language 是 z.string()(语言是配置项,随时可能加,收紧成枚举会让
// 新加的语言在后端 parse 时直接抛),前端在这一处收窄成 LANGUAGE
return api.get<{ results: SubmissionListItem[]; total: number }>(endpoint, {
// contestId 走的是路径page 只有前端分页器用
params: { ...params, contestId: undefined, page: undefined },
})
return getSubmissionPage(endpoint, params)
}
/**
* 提交列表。后端在 `submissionListItemSchema.parse` 上真的会抛 —— 它逐个列表项
* 过 schema所以这条链路上的分歧**后端自己就拦住了**,前端这层校验是第二道保险:
* 主要防「后端加了字段但契约没跟上、前端类型声称有实际是 undefined」这类
* 只在展示端出问题的偏差。
*/
async function getSubmissionPage(
endpoint: string,
params: Partial<SubmissionListPayload>,
) {
return contract(
`GET /${endpoint}`,
submissionListSchema,
await api.get<unknown>(endpoint, {
// contestId 走的是路径page 只有前端分页器用
params: { ...params, contestId: undefined, page: undefined },
}),
)
}
export function getRankOfProblem(problemId: string) {

View File

@@ -2,8 +2,10 @@
import { Icon } from "@iconify/vue"
import { useThemeVars } from "naive-ui"
import { HINT_MIN_FAILURES } from "@oj2/contract"
import type { JudgeCaseResult } from "@oj2/contract"
import { JUDGE_STATUS, SubmissionStatus } from "utils/constants"
import {
submissionCaseResults,
submissionMemoryFormat,
submissionTimeFormat,
} from "utils/functions"
@@ -124,9 +126,12 @@ async function fetchHint(submissionId: string) {
// 测试用例表格数据(只在部分通过时显示)
const infoTable = computed(() => {
if (!props.submission?.info?.data?.length) return []
const submission = props.submission
if (!submission) return []
const data = submissionCaseResults(submission.info)
if (!data.length) return []
const result = props.submission.result
const result = submission.result
// AC、编译错误、运行时错误不显示测试用例表格
if (
result === SubmissionStatus.accepted ||
@@ -137,13 +142,12 @@ const infoTable = computed(() => {
return []
}
const data = props.submission.info.data
// 只有存在失败的测试用例时才显示
return data.some((item) => item.result === 0) ? data : []
})
// 测试用例表格列配置
const columns: DataTableColumn<Submission["info"]["data"][number]>[] = [
const columns: DataTableColumn<JudgeCaseResult>[] = [
{ title: "测试用例", key: "test_case" },
{
title: "测试状态",

View File

@@ -1,5 +1,6 @@
<script setup lang="ts">
import { getSubmission } from "oj/api"
import type { JudgeCaseResult } from "@oj2/contract"
import {
JUDGE_STATUS,
LANGUAGE_FORMAT_VALUE,
@@ -7,6 +8,7 @@ import {
} from "utils/constants"
import {
parseTime,
submissionCaseResults,
submissionMemoryFormat,
submissionTimeFormat,
utoa,
@@ -36,6 +38,12 @@ const { isMobile, isDesktop } = useBreakpoints()
const submission = ref<Submission>()
const loading = ref(false)
/**
* 测试点明细。`info` 在契约里是「完整形状或空对象」的联合(非管理员拿到的是空对象),
* `data` 本身也可能为 null —— 两种情况都由这个访问器归成空数组,模板里不再直接取。
*/
const caseResults = computed(() => submissionCaseResults(submission.value?.info))
async function init() {
submission.value = props.submission
if (submission.value) return
@@ -45,7 +53,7 @@ async function init() {
loading.value = false
}
const columns: DataTableColumn<Submission["info"]["data"][number]>[] = [
const columns: DataTableColumn<JudgeCaseResult>[] = [
{ title: "测试用例", key: "test_case" },
{
title: "测试状态",
@@ -149,9 +157,9 @@ onMounted(init)
/>
</n-card>
<n-data-table
v-if="!hideList && submission.info && submission.info.data"
v-if="!hideList && caseResults.length"
:columns="columns"
:data="submission.info.data"
:data="caseResults"
/>
</n-flex>
<n-spin v-else :show="loading" class="loading-container"> </n-spin>

View File

@@ -1,5 +1,6 @@
import { userProfileSchema, type Quote } from "@oj2/contract"
import api from "utils/api"
import { contract } from "utils/contract"
import type { Profile, Tag } from "utils/types"
export function login(data: { username: string; password: string }) {
@@ -21,12 +22,14 @@ export function logout() {
export async function getProfile(
username: string = "",
): Promise<Profile | null> {
const response = await api.get<unknown>(
username ? `profiles/${encodeURIComponent(username)}` : "me",
)
const endpoint = username ? `profiles/${encodeURIComponent(username)}` : "me"
const response = await api.get<unknown>(endpoint)
if (response === null) return null
// 形状与契约一致,不再逐字段搬运zod 解析仍保留,形状对不上要当场炸
return userProfileSchema.parse(response) as Profile
// 形状与契约一致,不再逐字段搬运。走契约闸门而不是裸 parse():原来这里是
// `userProfileSchema.parse(response) as Profile``as` 把校验结果又断言回本地
// 类型Profile 把 user 收窄成 SessionUser、acmProblemsStatus 收窄成具体形状),
// 形状对不上时页面白屏。现在记一条分歧日志后放行原始数据。
return contract("GET /profiles/:username", userProfileSchema, response)
}
export function getProblemTagList() {

View File

@@ -0,0 +1,132 @@
import type { z } from "zod"
/**
* 契约的运行时闸门。
*
* ## 为什么要有这一层
*
* `@oj2/contract` 的收益只有一半是类型:`z.infer` 给出编译期的形状,但**编译期
* 管不了后端实际下发了什么**。改后端字段、drizzle 改名、序列化时漏一个键,
* TypeScript 一概看不见,页面上表现为某个 `undefined` 静默渲染成空白。
* 契约真正的价值在于同一份 schema 能在运行时把这种分歧当场抓出来。
*
* 原来只有三处调用 `.parse()`,而且**后面都紧跟一个 `as`** 把它重新断言回本地
* 类型(`problemDetailSchema.parse(v) as Problem`)—— 校验结果被丢弃,等于没校验。
*
* ## 失败策略:记日志 + 放行原始数据
*
* **不抛错。** 这是面向学生的生产站点,契约分歧的代价不该是白屏 —— 少了哪个
* 字段,页面大体上照样能用,只是那处空着。所以解析失败时:
*
* 1. `console.error` 一条带端点和字段路径的记录,开发时一眼能看到;
* 2. 记进 `window.__OJ2_CONTRACT_DRIFT__`(同一条只记一次),排查线上问题时
* 可以直接在控制台敲这个变量看全部历史;
* 3. **返回原始数据**,让页面继续渲染。
*
* 用 `safeParse` 而不是 `parse``parse` 抛出的 ZodError 会把调用方整个 async
* 函数打断,`getProblem` 一失败,整个题目页就只剩白屏。
*
* ## 什么时候该升级成硬失败
*
* 等 `__OJ2_CONTRACT_DRIFT__` 在某条路径上稳定为空之后,那条路径就可以换成
* 直接 `schema.parse()` —— 分歧修完了,剩下的任何分歧都是新引入的真 bug
* 那时白屏反而是对的。**在那之前不要硬失败**,机房上课时炸一个页面比字段空着严重得多。
*/
/**
* 见过的分歧。只留前若干条实例,避免一个列表接口几百条记录把内存堆满 ——
* 每条记录的形状问题是一样的,一条实例足够定位。
*/
interface DriftReport {
/** 请求路径,带参数,方便直接复现 */
endpoint: string
/** zod 的 issue 摘要:路径 + 原因,多条用分号连 */
detail: string
/** 实际收到的数据。截断后的原始值,用来判断是字段缺失还是类型不同 */
received: unknown
/** 出现次数。同一个端点同一个 detail 只记一条,这里累加 */
count: number
}
const MAX_REPORTS = 200
const MAX_RECEIVED_CHARS = 2000
declare global {
interface Window {
__OJ2_CONTRACT_DRIFT__?: DriftReport[]
}
}
function collectDrift(endpoint: string, detail: string, received: unknown) {
if (typeof window === "undefined") return
const reports = (window.__OJ2_CONTRACT_DRIFT__ ??= [])
// 同一个端点 + 同一个原因只记一条,累加次数。列表接口一次几百条记录,
// 不去重的话控制台会被同一句话刷屏,真正的新问题反而看不见。
const existing = reports.find(
(item) => item.endpoint === endpoint && item.detail === detail,
)
if (existing) {
existing.count += 1
return
}
if (reports.length >= MAX_REPORTS) return
reports.push({
endpoint,
detail,
received: truncate(received),
count: 1,
})
}
/** 原始数据可能是一整个列表页,原样留着会占住大量内存;只用来判断形状,够看前 2KB 了 */
function truncate(value: unknown) {
try {
const text = JSON.stringify(value)
if (text === undefined) return value
return text.length <= MAX_RECEIVED_CHARS
? value
: `${text.slice(0, MAX_RECEIVED_CHARS)}…(截断,共 ${text.length} 字符)`
} catch {
return String(value)
}
}
function describe(error: z.ZodError, endpoint: string) {
const issues = error.issues.slice(0, 5).map((issue) => {
const path = issue.path.length ? issue.path.join(".") : "(根)"
return `${path}: ${issue.message}`
})
const more = error.issues.length > 5 ? `;另有 ${error.issues.length - 5}` : ""
return `${endpoint} 的响应不符合契约 —— ${issues.join("")}${more}`
}
/**
* 校验并返回响应。用 `unknown` 进来的数据出去就是契约类型,不需要再 `as`。
*
* ```ts
* const data = await api.get<unknown>("problems", { params })
* return contract("GET /problems", problemListSchema, data)
* ```
*
* 端点字符串是手写的,刻意不让调用方漏掉 —— 它只用于日志和去重,写错不影响正确性。
*/
export function contract<T extends z.ZodType>(
endpoint: string,
schema: T,
value: unknown,
): z.infer<T> {
const result = schema.safeParse(value)
if (result.success) return result.data
collectDrift(endpoint, describe(result.error, endpoint), value)
console.error(
`[契约] ${describe(result.error, endpoint)}\n` +
" 已放行原始数据(页面照常渲染)。全部历史分歧见 window.__OJ2_CONTRACT_DRIFT__。\n" +
" 契约在 packages/contract/src/,后端对不上的字段在 apps/api/src/routes/。",
)
// 放行原始数据。断言在这里是**有意的**:形状确实可能不符,但调用方需要的是
// 「能渲染的东西」而不是一个异常;分歧已经通过上面两条记录暴露出来了。
return value as z.infer<T>
}

View File

@@ -1,4 +1,5 @@
import { toAdminType } from "@oj2/contract"
import type { JudgeCaseResult, SubmissionDetail } from "@oj2/contract"
import { getTime, intervalToDuration, parseISO, type Duration } from "date-fns"
import { User } from "./types"
import { USER_TYPE } from "./constants"
@@ -19,6 +20,23 @@ function calculateACRate(acCount: number, totalCount: number): string {
return ((acCount / totalCount) * 100).toFixed(2)
}
/**
* 从 `submission.info` 里取测试点明细,取不到就返回空数组。
*
* 契约里 `info` 是**联合类型**:判题机写的完整形状,或者空对象 —— 后者是后端对
* 非管理员下发的权限投影(`routes/submission.ts` 的 `full ? row.submission.info : {}`
* 也是待判提交的初值。所以调用方不能直接 `.data`,得先在这里收口。
*
* 另外 `data` 本身也可能是 null生产库 124191 条提交里有 12048 条是编译失败之类
* 没有逐测试点结果的情形。两种「没有」在这里一并归成空数组。
*/
export function submissionCaseResults(
info: SubmissionDetail["info"] | null | undefined,
): JudgeCaseResult[] {
if (!info || !("data" in info) || !info.data) return []
return info.data
}
export function getACRate(acCount: number, totalCount: number): string {
return `${calculateACRate(acCount, totalCount)}%`
}

View File

@@ -15,6 +15,7 @@ import type {
JudgeStatus,
AstRules,
CreateAnnouncementRequest,
ProblemLanguage,
} from "@oj2/contract"
/**
@@ -45,16 +46,17 @@ export type User = AdminUser & {
password?: string
}
export type LANGUAGE =
| "C"
| "C++"
| "Python2"
| "Python3"
| "Java"
| "JavaScript"
| "Golang"
| "Flowchart"
| "SQL"
/**
* 语言联合。**从契约派生,不再手抄** —— 原来这里手写了一份 9 个值的联合,
* 而后端 `judge/languages.ts` 与生产库各有自己的答案,三份真相各自演进:
* 手抄那份漏了 `SQL`,于是生产库里 91 条 SQL 提交的 `language` 在类型上是
* `undefined`(提交列表、表情组件都按它渲染)。现在唯一来源是契约的
* `problemLanguageSchema`,见 packages/contract/src/language.ts。
*
* constants.ts 的 SOURCES / LANGUAGE_FORMAT_VALUE / LANGUAGE_SHOW_VALUE
* 都以它为键 —— 契约里加一种语言而那边没补映射,会当场编译不过。
*/
export type LANGUAGE = ProblemLanguage
/**
* SQL 题的配置与展示数据。形状在契约里 —— 原来这里手抄了一份,
@@ -262,74 +264,25 @@ export type {
export type { CreateFlowchartRequest as SubmitFlowchartPayload } from "@oj2/contract"
/**
* 判题机原始输出。契约里是 `info: z.unknown()` —— 后端不校验沙箱产物,
* 这些键名是沙箱定的,**保持 snake_case**,不要跟着响应字段一起改名。
* 提交详情。**info / statisticInfo / language 三处窄化都搬进契约了**
* `judgeInfoSchema` / `statisticInfoSchema` / `problemLanguageSchema`
* 依据是生产库 124191 条提交的实测分布,见 packages/contract/src/submission.ts。
*
* 前端仍要保留一处:`result` 多一个 9 —— 点了提交、还没拿到结果时前端本地先填的
* 伪状态,后端永远不会下发,见 constants.ts 的 SubmissionStatus.submitting。
* 这是「前端自己造的状态」,不属于契约能描述的东西。
*/
interface Info {
err: string | null
data: {
error: number
memory: number
output: null
result: SUBMISSION_RESULT
signal: number
cpu_time: number
exit_code: number
real_time: number
test_case: string
output_md5: string
}[]
}
/**
* 判题产出的统计。**键名保持 snake_case** —— 这是 submission.statistic_info
* JSONB 的原文,判题机按这套键名写进去,不能跟着响应字段一起改名。
*/
export interface StatisticInfo {
score?: number
err_info?: string
time_cost?: number
memory_cost?: number
ast_results?: Array<{
description: string
passed: boolean
/** count_* 规则实际数到的次数,判题机只在这两个引擎上写 */
actual?: number
}>
}
/**
* 提交详情。以契约的 SubmissionDetail 为准,只窄化两处 unknown
* `info` 是判题沙箱原始输出,`statisticInfo` 是判题写的 JSONB —— 两者内部都是 snake。
*/
export type Submission = Omit<
SubmissionDetail,
"info" | "statisticInfo" | "language" | "result"
> & {
info: Info
statisticInfo: StatisticInfo
language: LANGUAGE
// 比契约多一个 9点了提交、还没拿到结果时前端本地先填这个伪状态
// 见 constants.ts 的 SubmissionStatus.submitting
export type Submission = Omit<SubmissionDetail, "result"> & {
result: SUBMISSION_RESULT
}
/** 站内信里嵌的提交problem 是展示题号而非数字 id且不含 info / ip / contestId */
export type EmbeddedSubmission = Omit<
ContractEmbeddedSubmission,
"statisticInfo" | "language"
> & {
statisticInfo: StatisticInfo
language: LANGUAGE
}
/**
* 站内信里嵌的提交problem 是展示题号而非数字 id且不含 info / ip / contestId。
* 契约里已经窄化好了(`embeddedSubmissionSchema`),这里不再重复 Omit + 增补。
*/
export type EmbeddedSubmission = ContractEmbeddedSubmission
export type SubmissionListItem = Omit<
ContractSubmissionListItem,
"statisticInfo" | "language"
> & {
statisticInfo: StatisticInfo
language: LANGUAGE
}
export type SubmissionListItem = ContractSubmissionListItem
export interface SubmissionListPayload {
myself?: "1" | "0"