Просмотр исходного кода

⚡️ (term): 社区译名表带 ETag,没变回 304、不查表

/v3/glossaries/community 的 channel 只由 upgrade:community.term 维护,任务跑完在 Redis 里
换一个 uuid 作为 ETag(再拼上响应结构版本号 GlossaryService::SCHEMA_VERSION,Resource
改字段要加 1)。请求带 If-None-Match 命中时在查表之前回 304(Symfony isNotModified,
弱比较,nginx 压缩后的 W/"…" 也认);Cache-Control: public, no-cache。grammar 表是人工
编辑的,暂不带 ETag。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
visuddhinanda 10 часов назад
Родитель
Сommit
198636fd77

Разница между файлами не показана из-за своего большого размера
+ 0 - 0
CLAUDE.md


+ 11 - 0
api-test/cases/17_glossaries.php

@@ -21,6 +21,17 @@ test('GET /v3/glossaries/community?lang=zh-Hans → 200,整表带 meta', funct
     }
 });
 
+test('GET /v3/glossaries/community 带 If-None-Match(表没变)→ 304,无正文', function () {
+    $first = raw('GET', '/v3/glossaries/community', ['lang' => 'zh-Hans']);
+    assert_status(200, $first, 'community glossary');
+    $etag = $first['headers']['etag'][0] ?? null;
+    if ($etag === null) {
+        throw new Fail('community glossary 应带 ETag');
+    }
+    $again = raw('GET', '/v3/glossaries/community', ['lang' => 'zh-Hans'], null, null, ['If-None-Match' => $etag]);
+    assert_status(304, $again, '条件请求');
+});
+
 test('GET /v3/glossaries/grammar?lang=xx(没有这种语言的表)→ 200,回退到 en', function () {
     $res = raw('GET', '/v3/glossaries/grammar', ['lang' => 'xx']);
     assert_status(200, $res, 'grammar glossary 回退');

+ 5 - 1
api-v13/app/Console/Commands/UpgradeCommunityTerm.php

@@ -7,6 +7,7 @@ use App\Models\DhammaTerm;
 use App\Models\Sentence;
 use App\Models\UserOperationDaily;
 use App\Services\ChannelService;
+use App\Services\V3\GlossaryService;
 use App\Tools\Tools;
 use Illuminate\Console\Command;
 use Illuminate\Support\Str;
@@ -32,7 +33,7 @@ class UpgradeCommunityTerm extends Command
      *
      * @return int
      */
-    public function handle(ChannelService $channels)
+    public function handle(ChannelService $channels, GlossaryService $glossaries)
     {
         if (Tools::isStop()) {
             return 0;
@@ -206,6 +207,9 @@ class UpgradeCommunityTerm extends Command
         $stale->each->delete();
         $this->info("done: {$total} terms, {$stale->count()} stale rows removed");
 
+        // 表可能变了:换 ETag,客户端(/v3/glossaries/community)下次请求拿新数据
+        $glossaries->rotateEtag($localTerm);
+
         return 0;
     }
 

+ 20 - 3
api-v13/app/Http/Controllers/V3/GlossaryController.php

@@ -6,6 +6,7 @@ use App\Http\Controllers\Controller;
 use App\Http\Requests\V3\IndexGlossaryRequest;
 use App\Http\Resources\V3\GlossaryEntryResource;
 use App\Services\V3\GlossaryService;
+use Illuminate\Http\Response;
 
 /**
  * 术语词汇表:语法术语表 / 社区译名表(只读)。
@@ -31,16 +32,32 @@ class GlossaryController extends Controller
      *
      * @meta kind string 哪张表
      * @meta lang string 实际用到的语言(没有该语言的表时是 en)
+     * community 表带 `ETag`(`Cache-Control: public, no-cache`):浏览器下次自动带 `If-None-Match`,
+     * 表没变就回 304、不带正文。ETag 在社区术语任务每次跑完时更换。grammar 表暂不带。
      * @meta total integer 条数
      */
     public function __invoke(IndexGlossaryRequest $request, string $kind)
     {
-        $result = $this->glossaries->entries($kind, $request->validated('lang') ?? app()->getLocale());
+        $lang = $request->validated('lang') ?? app()->getLocale();
+        $etag = $this->glossaries->etag($kind, $lang);
+        $withEtag = fn ($response) => $etag === null ? $response : $response
+            ->setEtag($etag)
+            ->header('Cache-Control', 'public, no-cache');
 
-        return GlossaryEntryResource::collection($result['items'])->additional(['meta' => [
+        // 表没变:在查整表之前就回 304(isNotModified 按 RFC 9110 弱比较,nginx 压缩后的 W/"…" 也认)
+        if ($etag !== null) {
+            $probe = $withEtag(new Response);
+            if ($probe->isNotModified($request)) {
+                return $probe;
+            }
+        }
+
+        $result = $this->glossaries->entries($kind, $lang);
+
+        return $withEtag(GlossaryEntryResource::collection($result['items'])->additional(['meta' => [
             'kind' => $kind,
             'lang' => $result['lang'],
             'total' => $result['items']->count(),
-        ]]);
+        ]])->response());
     }
 }

+ 63 - 7
api-v13/app/Services/V3/GlossaryService.php

@@ -2,9 +2,12 @@
 
 namespace App\Services\V3;
 
+use App\Facades\RedisCache;
+use App\Http\Resources\V3\GlossaryEntryResource;
 use App\Models\DhammaTerm;
 use App\Services\ChannelService as ChannelLookup;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
 
 /**
  * 术语词汇表(只读):语法术语表与社区译名表,客户端启动时整表拉取后本地查。
@@ -25,6 +28,15 @@ class GlossaryService
 
     private const FALLBACK_LANG = 'en';
 
+    /**
+     * 响应结构的版本,拼进 ETag。{@see GlossaryEntryResource} 的字段一改就加 1,
+     * 否则浏览器带着旧 ETag 来会拿到 304、继续用旧结构的缓存。
+     */
+    private const SCHEMA_VERSION = 2;
+
+    /** ETag 在 Redis 里的存活时间;本任务每天都会换新,过期了也只是让客户端多拉一次 */
+    private const ETAG_TTL = 30 * 24 * 60 * 60;
+
     public function __construct(private readonly ChannelLookup $channels) {}
 
     /**
@@ -34,13 +46,7 @@ class GlossaryService
      */
     public function entries(string $kind, string $lang): array
     {
-        $prefix = self::CHANNEL_PREFIX[$kind];
-        $served = $lang;
-        $channel = $this->channels->systemUid($prefix.strtolower($lang).'_');
-        if ($channel === false) {
-            $served = self::FALLBACK_LANG;
-            $channel = $this->channels->systemUid($prefix.self::FALLBACK_LANG.'_');
-        }
+        [$channel, $served] = $this->channelOf($kind, $lang);
 
         $items = $channel === false
             ? collect()
@@ -54,4 +60,54 @@ class GlossaryService
 
         return ['items' => $items, 'lang' => $served];
     }
+
+    /**
+     * 某种词汇表当前的 ETag;没有 ETag 的表(grammar)或表不存在时返回 null。
+     *
+     * 只有 community 有:它的 channel 只由 `upgrade:community.term` 维护,任务跑完调
+     * {@see rotateEtag()} 换一个新 uuid,所以不用查整表、不用算 hash。有人绕过任务手工改了这个
+     * channel,ETag 不会变,客户端要等下次任务跑完才看得到。grammar 是人工编辑的,暂不支持。
+     */
+    public function etag(string $kind, string $lang): ?string
+    {
+        if ($kind !== 'community') {
+            return null;
+        }
+        [$channel] = $this->channelOf($kind, $lang);
+        if ($channel === false) {
+            return null;
+        }
+
+        // key 不存在(刚部署、Redis 清过、过期)就现生成一个
+        $token = RedisCache::remember(self::etagKey($channel), self::ETAG_TTL, fn () => (string) Str::uuid());
+
+        return $token.'.'.self::SCHEMA_VERSION;
+    }
+
+    /** 词汇表 channel 的内容变了:换一个新 ETag,客户端下次请求会拿到 200 与新数据 */
+    public function rotateEtag(string $channel): void
+    {
+        RedisCache::put(self::etagKey($channel), (string) Str::uuid(), self::ETAG_TTL);
+    }
+
+    private static function etagKey(string $channel): string
+    {
+        return "/glossary/{$channel}/etag";
+    }
+
+    /**
+     * 实际要读的 channel 与语言:该语言没有这张表时回退到英文(与 v2 相同)。
+     *
+     * @return array{0: string|false, 1: string}
+     */
+    private function channelOf(string $kind, string $lang): array
+    {
+        $prefix = self::CHANNEL_PREFIX[$kind];
+        $channel = $this->channels->systemUid($prefix.strtolower($lang).'_');
+        if ($channel !== false) {
+            return [$channel, $lang];
+        }
+
+        return [$this->channels->systemUid($prefix.self::FALLBACK_LANG.'_'), self::FALLBACK_LANG];
+    }
 }

+ 1 - 1
api-v13/documents/tasks.md

@@ -53,7 +53,7 @@ start at: 16:00 UTC
 # 更新单词首选意思
 php artisan upgrade:dict.default.meaning
 
-# 社区术语表
+# 社区术语表(这个 channel 只由本任务维护;跑完会换 /v3/glossaries/community 的 ETag)
 php artisan upgrade:community.term zh-Hans
 
 # 导出离线数据

+ 37 - 0
api-v13/tests/Feature/GlossaryV3Test.php

@@ -1,7 +1,9 @@
 <?php
 
 use App\Models\DhammaTerm;
+use App\Services\V3\GlossaryService;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
 
 uses(RefreshDatabase::class);
@@ -93,3 +95,38 @@ it('gives the term guid only in the grammar glossary, and never the auto-increme
         ->and(json_encode($row))->not->toContain($community->guid)
         ->and(json_encode($row))->not->toContain((string) $community->id);
 });
+
+it('answers 304 for an unchanged community glossary without loading it, and 200 after the task rotates the ETag', function () {
+    $zh = makeChannel(config('mint.admin.root_uuid'), '_community_term_zh-hans_');
+    glossaryTerm($zh, 'dhamma');
+
+    $first = $this->getJson('/api/v3/glossaries/community?lang=zh-Hans')->assertOk();
+    $etag = $first->headers->get('ETag');
+    expect($etag)->not->toBeEmpty()
+        ->and($first->headers->get('Cache-Control'))->toContain('no-cache')->toContain('public')
+        ->and($first->headers->get('Vary'))->toContain('Accept-Language');
+
+    DB::enableQueryLog();
+    $this->getJson('/api/v3/glossaries/community?lang=zh-Hans', ['If-None-Match' => $etag])
+        ->assertStatus(304)
+        ->assertHeader('ETag', $etag)
+        ->assertContent('');
+    // nginx gzip 会把 ETag 改成弱校验 W/"…",浏览器带回来的也是它
+    $this->getJson('/api/v3/glossaries/community?lang=zh-Hans', ['If-None-Match' => 'W/'.$etag])->assertStatus(304);
+    $loaded = collect(DB::getQueryLog())->contains(fn ($q) => str_contains($q['query'], 'dhamma_terms'));
+    expect($loaded)->toBeFalse();
+
+    app(GlossaryService::class)->rotateEtag($zh);
+
+    $fresh = $this->getJson('/api/v3/glossaries/community?lang=zh-Hans', ['If-None-Match' => $etag])->assertOk();
+    expect($fresh->headers->get('ETag'))->not->toBe($etag)
+        ->and($fresh->json('data.*.word'))->toBe(['dhamma']);
+});
+
+it('gives no ETag for the grammar glossary or a missing table', function () {
+    $grammar = makeChannel(config('mint.admin.root_uuid'), '_System_Grammar_Term_zh-hans_');
+    glossaryTerm($grammar, 'vibhatti');
+
+    expect($this->getJson('/api/v3/glossaries/grammar?lang=zh-Hans')->assertOk()->headers->has('ETag'))->toBeFalse()
+        ->and($this->getJson('/api/v3/glossaries/community?lang=zh-Hans')->assertOk()->headers->has('ETag'))->toBeFalse();
+});

+ 11 - 0
api-v13/tests/Feature/UpgradeCommunityTermTest.php

@@ -2,6 +2,7 @@
 
 use App\Models\Channel;
 use App\Models\DhammaTerm;
+use App\Services\V3\GlossaryService;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Str;
 
@@ -99,6 +100,16 @@ it('never takes the note from an AI-generated channel, but still counts its mean
         ->and((string) $term->note)->toBe('');
 });
 
+it('rotates the community glossary ETag after each run', function () {
+    communityTerm($this->user, 'dhamma', null);
+    $glossaries = app(GlossaryService::class);
+    $before = $glossaries->etag('community', 'zh-Hans');
+
+    $this->artisan('upgrade:community.term', ['lang' => 'zh-Hans'])->assertSuccessful();
+
+    expect($glossaries->etag('community', 'zh-Hans'))->not->toBe($before);
+});
+
 it('only touches the given word when one is passed', function () {
     communityTerm($this->user, 'dhamma', null);
     communityTerm($this->user, 'sīla', null);

+ 2 - 0
dashboard-v6/src/api/schema.d.ts

@@ -8565,6 +8565,8 @@ export interface paths {
          * 术语词汇表
          * @description 整表返回、不分页(客户端启动时拉一次,本地查词)。`meta.lang` 是实际用到的语言:
          *     该语言没有这张表时回退到英文。条目的 `id`(术语 guid)只有 grammar 表给,community 表不给(省流量)。
+         *     community 表带 `ETag`(`Cache-Control: public, no-cache`):浏览器下次自动带 `If-None-Match`,
+         *     表没变就回 304、不带正文。ETag 在社区术语任务每次跑完时更换。grammar 表暂不带。
          *
          *     实现:`V3\GlossaryController@__invoke`
          */

+ 2 - 0
openapi/public/assets/protocol/resources/auto/v3-glossaries-kind.yaml

@@ -7,6 +7,8 @@ get:
   description: |-
     整表返回、不分页(客户端启动时拉一次,本地查词)。`meta.lang` 是实际用到的语言:
     该语言没有这张表时回退到英文。条目的 `id`(术语 guid)只有 grammar 表给,community 表不给(省流量)。
+    community 表带 `ETag`(`Cache-Control: public, no-cache`):浏览器下次自动带 `If-None-Match`,
+    表没变就回 304、不带正文。ETag 在社区术语任务每次跑完时更换。grammar 表暂不带。
 
     实现:`V3\GlossaryController@__invoke`
   security:

Некоторые файлы не были показаны из-за большого количества измененных файлов