简介BiliRaffle 是面向 B 站动态抽奖场景的 C# 开源桌面工具基于 .NET Framework 4.5 及以上运行适合希望直接使用抽奖功能或需要研究动态抽奖实现、进行二次开发的用户。压缩包共 32 个文件整体约 60KB以 12 个 cs 源码和 4 个 xaml 界面文件为核心另含 config、xml、dll、图标图片、解决方案及开源许可等结构紧凑覆盖登录、主界面、视图模型与抽奖逻辑等模块。现有 697 人学习说明其在 B 站工具类资源中具有一定关注度。读者可从中了解 C# 桌面端如何组织 MVVM 结构、接入 B 站相关接口、处理登录状态与抽奖流程也能据此排查依赖版本、运行环境和配置问题。代码围绕动态数据获取、条件筛选与结果展示形成较完整的小型工具链路适合作为源码阅读、功能拆解与二次改造的参考样例。1. 手动翻转发列表翻到眼花之后我把抽奖交给了 BiliRaffle一次活动动态挂了三天转发数冲到四位数负责发奖的同事从第一页翻到最后一页复制、粘贴、去重干了两个多小时最后名单里还混进几个早就取关的账号。这事之后我开始找能脚本化的方案翻到了 BiliRaffle——一个用 C# 写的 B 站动态抽奖组件。它做的事不玄学围绕 bilibili-api 把「取动态转发列表 → 校验参与资格 → 按 mid 去重 → 随机开奖 → 结果落盘」串成一条可重复执行的流程参数从命令行进结果从文件出。适合自己办小活动、需要一份能复盘的开奖记录的开发者也适合拿它当 bilibili-tool 学习样本、想看 C# 怎么封装带 Cookie 的分页接口的人不适合指望点两下就出结果的人后面几章会讲清门槛在哪。2. 先看懂骨架再动手BiliRaffle 的分层、调用链与首次跑通拿到一个 C# 组件最容易犯的错是直接dotnet run然后就着报错乱改。我一般的顺序是先把目录结构和调用链读一遍搞清楚哪一层负责发请求、哪一层负责判断规则、哪一层负责写文件再决定动哪里。BiliRaffle 的分层很薄几乎是为「一个脚本干一件事」这个目标裁出来的读起来不费劲但也意味着它不替你兜底——参数传错它会老老实实按错的方式跑完。2.1 三个目录扛下全部职责Api、Raffle 与 Output仓库里真正承担业务逻辑的只有三块剩下的都是胶水。我把它们和对应的关键类型列成表进场先对着这张表定位后面出问题基本能一眼看出该去看哪个文件。目录 / 文件职责边界典型类型Api/对 bilibili-api 的薄封装只负责组请求、带 Cookie、反序列化不含任何抽奖判断BiliApiClient、ApiResultTRaffle/参与者采集、过滤链、随机开奖纯内存计算不发请求ParticipantCollector、FilterChain、RaffleEngineOutput/参与者快照、中奖名单、开奖清单的序列化CsvWriter、ResultManifestProgram.cs命令行解析与依赖组装一行业务判断都不写CommandLineOptionsConfig/规则与限速参数的默认值RaffleRules、ThrottleOptions这个划分的直接好处是调接口出问题只看Api/抽出来的名单不对只看Raffle/文件格式不对只看Output/。很多同类小工具把三者揉在一个Main里几百行之后谁也不敢改这是我不太推荐的做法。Api/这层的设计取向值得单独说一句。它没有做通用 SDK不做签名、不做登录态刷新只接受一个已经拼好的 Cookie 字符串然后按接口路径发 GET。换句话说它把 bilibili-api 当成「一组需要鉴权的 HTTP 端点」来对待而不是当成一个有状态的客户端对象。这种薄封装在一次性抽奖场景里足够代价是所有鉴权细节都暴露给调用方Cookie 过期了它不会帮你换只会返回一个空列表或者一个错误码后面第 4 章会专门讲怎么识别。Raffle/里最需要注意的是FilterChain。它是有序执行的顺序不同结果可能不同。比如先按时间窗筛、再按关注状态筛和反过来做在网络抖动导致关注状态查不到时行为会有差别。仓库默认的顺序是先做本地就能判断的条件时间窗、是否重复、是否在自己维护的黑名单里再做需要额外请求的条件关注状态。这个顺序是有道理的把贵的判断放后面能省掉大量无效请求。Output/只有两个写入器一个写 CSV一个写 JSON 清单。CSV 给人看JSON 给校验用。这里有一个设计选择——写文件用的是覆盖而不是追加每次运行都会生成新的带时间戳的文件名。刚开始我觉得啰嗦后来发现这是好事你不会因为一次失败的重跑把上一次成功的快照冲掉。2.2 从 Cookie 到中奖名单一次抽奖走过的七个环节把整条链路摊平一次完整运行其实是七步。每一步都可能失败也都留下可观察的痕迹排错时按这个顺序往下捋比漫无目的地看日志快得多。解析命令行参数得到动态 ID、抽奖人数、规则配置文件路径、输出目录。用 Cookie 初始化 HTTP 客户端设置 UA 与超时。请求动态详情确认这条动态存在、是转发抽奖类型、当前状态可读。分页拉取转发列表逐页追加到内存列表同时记录每一页的游标。把原始参与者列表写成快照文件先落盘再过滤——这一步是后面所有争议的「后悔药」。按过滤链逐条判定得到合格参与者集合按 mid 去重。用随机引擎抽取 N 名中奖者写中奖名单和开奖清单。第三步容易被跳过我建议保留。动态详情里能拿到转发总数这个数字可以和第四步实际拉到的条数做交叉比对。如果详情说 3200 条转发你只拉到 800 条就结束了分页那一定是分页逻辑或限速出了问题此时抽出来的名单是不可信的。这种「先对账再开奖」的习惯是我踩过几次坑之后强制加进流程里的。第五步的「先落盘再过滤」同样是血泪经验。过滤规则是可以改的改完重跑一遍很快但如果你没留原始快照重跑就得重新拉一遍几千条转发既慢又可能因为接口波动拿到不一样的数据集。有了快照你甚至可以离线反复调整规则不用再碰网络。2.3 环境跑通.NET SDK、还原依赖与第一条命令环境部分没有太多花样C# 项目对环境的要求就是 SDK 版本对得上。我一般用当前 LTS 版本的 .NET SDK版本太老会在还原阶段就因为语言特性报错。先确认环境再还原最后才跑。# 确认 SDK 版本低于项目 TargetFramework 会在还原阶段直接报错 dotnet --info # 还原依赖这一步只走 NuGet不涉及任何接口调用 dotnet restore ./BiliRaffle.sln # 编译先保证能编过再谈运行 dotnet build ./BiliRaffle.sln -c Release --no-restore编译通过之后再跑第一次。第一次不要直接抽奖先用「只采集不开奖」的模式把参与者拉下来看看数量对不对。# --dry-run 只采集与过滤不执行开奖输出参与者快照 dotnet run --project ./src/BiliRaffle -- \ --dynamic-id 123456789012345678 \ --cookie $BILI_COOKIE \ --winners 1 \ --rules ./config/rules.json \ --out ./out \ --dry-run参数逐个说清楚这几个是最常改的--dynamic-id动态 ID从动态链接里取数字部分。注意不是用户 UID两者长度和含义都不同传错会得到一个「动态不存在」的返回。--cookie完整 Cookie 字符串从浏览器开发者工具里整段复制。这里用环境变量传入是为了避免它被写进 shell 历史和提交记录。--winners中奖人数。超过合格参与者数量时不同实现行为不同BiliRaffle 的做法是取全部并给出提示不会补位重抽。--rules规则配置路径不传就用内置默认值。默认值通常偏宽松正式活动建议显式传。--out输出目录不存在会自动创建同一秒内重复运行会覆盖同名文件。--dry-run只采集不开奖。第一次运行强烈建议带上先看参与者数量是否和动态页面上显示的转发数对得上。--dry-run跑完out/下应该出现一个带时间戳的参与者 CSV。打开它看三件事行数、表头、有没有明显的重复 mid。行数对不上就先别往下走去第 5 章找对应的排查条目。3. 把规则写进代码参与资格过滤、分页快照与开奖算法规则这块是整个组件里最容易被低估的部分。很多人以为抽奖就是Random.Next一下实际上真正决定结果可信度的是「谁进了候选池」。候选池错了随机算法再漂亮也没意义。BiliRaffle 把规则拆成可组合的过滤器这个设计我认为是对的因为活动规则每次都不一样硬编码进去必然要改代码。3.1 四类过滤器关注状态、转发时间窗、 数量与黑名单过滤器在代码里是一个很小的接口每个实现只回答一个问题这个人算不算合格参与者。不合格时给出原因字符串方便后面统计「被筛掉的人分别因为什么」。// 每个过滤器只做一个判断返回 false 时带上原因便于事后统计 public interface IParticipantFilter { bool Accept(Participant p, RaffleContext ctx, out string reason); } // 时间窗过滤只认活动开始时间之后、截止时间之前的转发 public sealed class TimeWindowFilter : IParticipantFilter { private readonly DateTimeOffset _from; private readonly DateTimeOffset _to; public TimeWindowFilter(DateTimeOffset from, DateTimeOffset to) { _from from; _to to; } public bool Accept(Participant p, RaffleContext ctx, out string reason) { // 转发时间统一用 UTC 比较避免本地时区带来的跨天误差 if (p.ForwardTime _from || p.ForwardTime _to) { reason out_of_window; return false; } reason string.Empty; return true; } }TimeWindowFilter里那个 UTC 比较不是多余的。活动配置里写的是「10 月 1 日 00:00 到 10 月 7 日 23:59」如果按本地时间解析、按接口返回的时间戳比较中间就会差出几个小时边界上的参与者会被误杀或者误放进来。我一般的做法是配置文件里显式带时区偏移解析后立刻转 UTC全程不再碰本地时间。另外三个过滤器分别是关注状态、 数量和黑名单。关注状态需要额外请求所以放在过滤链靠后的位置 数量取决于你对活动规则的定义有的活动要求 一位好友有的不要求这个只能按活动实际情况配黑名单是纯本地列表用来排除已知的异常账号或者内部人员跑在第一位最省请求。过滤链的顺序写在配置里不在代码里这一点很重要。活动规则变了改配置就行不用重新编译。{ rules: { filters: [blacklist, timeWindow, atCount, following], from: 2024-10-01T00:00:0008:00, to: 2024-10-07T23:59:5908:00, minAtCount: 1, requireFollowing: true } }配置里的filters数组就是执行顺序。把following放最后是因为它是唯一需要发请求的一环前面的本地过滤能砍掉多少人就砍掉多少人。3.2 分页快照为什么必须先把参与者全量落盘再抽奖分页拉取这件事表面上是个循环实际藏着三个坑游标什么时候算结束、单页返回空是不是真的没了、翻页过程中的数据变动怎么处理。先说结束条件。很多接口在最后一页会返回一个空列表但也有一些会在最后一页返回一个不满的列表而不是空列表。如果你的循环条件是「返回条数小于页大小就停」遇到前者会多请求一次遇到后者会正常结束。如果你的条件是「返回空就停」那遇到后者就会漏掉最后一页。稳妥的写法是两个条件都判并且加一个最大页数上限兜底防止因为接口异常导致死循环。再说翻页过程中的变动。抽奖活动进行中转发数是在实时增长的。你从第一页翻到最后一页可能要几十秒这期间新进来的转发会插在列表前面导致你翻到后面时前面已经翻过的位置内容整体后移出现重复或者跳过。这个问题没有完美解因为接口不提供一致性快照。能做的是翻完之后按 mid 去重并且记录一个采集起止时间在开奖说明里写清楚「以某时刻采集到的转发列表为准」。所以快照这一步不只是「留个备份」它是整个流程的事实基准。我的习惯是快照文件用participants-{dynamicId}-{timestamp}.csv命名字段至少包含 mid、昵称、转发时间、原始页码。// 采集结果先写盘再进入过滤保证任何一次开奖都能追溯到原始数据集 public sealed class ParticipantCollector { private readonly BiliApiClient _api; private readonly int _pageSize; public ParticipantCollector(BiliApiClient api, int pageSize 20) { _api api; _pageSize pageSize; } public async TaskIReadOnlyListParticipant CollectAsync( long dynamicId, int maxPages, CancellationToken ct) { var all new ListParticipant(); var seen new HashSetlong(); string? cursor null; for (int page 0; page maxPages; page) { // 每页之间由限速器控制节奏不在循环里手动 sleep var result await _api.GetRepostPageAsync(dynamicId, cursor, _pageSize, ct); if (!result.IsSuccess || result.Items.Count 0) break; foreach (var item in result.Items) { // 翻页期间数据会前移同一 mid 可能被重复返回 if (seen.Add(item.Mid)) all.Add(item); } cursor result.NextCursor; if (string.IsNullOrEmpty(cursor)) break; // 游标为空表示到底 } return all; } }代码里三个细节值得单独点出来。seen这个 HashSet 同时承担去重和终止判断——如果某一页返回的条目全部是已见过的说明已经在原地打转可以直接停。maxPages是个保险丝按「预估转发数 / 页大小 × 2」估算超了就是异常。游标为空作为结束信号比「返回条数小于页大小」更可靠前提是接口确实返回了游标。3.3 开奖随机性Fisher-Yates 与可复现的随机种子随机这块Random.Next直接在列表里取 N 次是不能用的因为会取到重复。正确的做法是先洗牌再取前 N 个洗牌用 Fisher-Yates复杂度 O(n)结果均匀。// Fisher-Yates 洗牌每个排列等概率取前 n 个即为不重复的随机中奖者 public static IReadOnlyListT ShuffleT(IReadOnlyListT source, Random rng) { var buffer source.ToArray(); for (int i buffer.Length - 1; i 0; i--) { int j rng.Next(i 1); (buffer[i], buffer[j]) (buffer[j], buffer[i]); } return buffer; } // 开奖入口种子显式传入便于事后复现同一份名单 public IReadOnlyListParticipant Draw( IReadOnlyListParticipant pool, int count, int seed) { var rng new Random(seed); return Shuffle(pool, rng).Take(Math.Min(count, pool.Count)).ToList(); }seed为什么不让它自动生成因为抽奖这件事天然会被质疑。有了显式种子和参与者快照任何人都能在本地用同一个种子重跑一遍得到完全一致的中奖名单。这是最有力的自证方式比截图有用得多。种子本身可以公开它不是秘密只是复现的钥匙。bilibili-raffle 类的工具在这块常见的分歧是「要不要给参与者加权」。我的看法是除非活动规则里明确写了加权比如连续转发多天加权否则一律等概率。加权会引入一堆解释成本而且权重配置一旦出错很难被发现。4. 接口这头的现实问题Cookie 生命周期、限速与异常分档本地逻辑写得再干净跑起来还是会被接口教做人。这一章讲三个必然会遇到的东西Cookie 什么时候失效、请求发多快算合适、报错之后该重试还是该停。4.1 Cookie 三件套与失效的三种表现B 站的登录态 Cookie 里真正决定能不能拿到数据的通常是三个字段一个标识会话、一个用于校验、一个标识用户 ID。BiliRaffle 不做登录流程它只是把整段 Cookie 塞进请求头所以这三个字段必须由你自己从浏览器里取而且要取全。少一个的表现各不相同少会话字段通常直接返回未登录少校验字段在只读接口上可能还能用但一旦触发需要校验的路径就失败少用户 ID 字段有时候能读到公开数据但读不到需要身份的字段。失效的表现有三种区分清楚能省很多时间第一种是直接返回未登录错误码这种最好处理换 Cookie 重跑。 第二种是返回空列表HTTP 状态是 200看起来一切正常。这种最坑因为你的流程会「成功」跑完只是参与者数量是 0。所以第 2 章里强调的「先对账」在这里就派上用场了。 第三种是触发风控返回 412 或者一个特定的负数错误码。这种通常不是 Cookie 本身过期而是请求特征异常比如频率太高、UA 不对、短时间内换了 IP 段。我的习惯是拿到 Cookie 之后先跑一次最小的探测请求比如读自己的用户信息确认身份有效再开始正式采集。这一步几十毫秒能避免后面几千条数据白拉。4.2 限速器怎么写令牌桶与抖动退避限速不是「每页 sleep 一秒」这么简单。固定 sleep 的问题是如果一次请求本身花了 800 毫秒你实际间隔是 1.8 秒浪费如果请求很快返回间隔又变成 1 秒节奏不均。更合理的做法是令牌桶控制的是长期平均速率允许一定程度的突发。// 令牌桶capacity 控制突发refillPerSecond 控制长期平均 QPS public sealed class TokenBucket { private readonly double _capacity; private readonly double _refillPerSecond; private double _tokens; private DateTimeOffset _lastRefill; public TokenBucket(double capacity, double refillPerSecond) { _capacity capacity; _refillPerSecond refillPerSecond; _tokens capacity; _lastRefill DateTimeOffset.UtcNow; } public async Task WaitAsync(CancellationToken ct) { while (true) { var now DateTimeOffset.UtcNow; var elapsed (now - _lastRefill).TotalSeconds; _tokens Math.Min(_capacity, _tokens elapsed * _refillPerSecond); _lastRefill now; if (_tokens 1) { _tokens - 1; return; } // 按缺口时长精确等待而不是固定 sleep 一整秒 var waitMs (int)Math.Ceiling((1 - _tokens) / _refillPerSecond * 1000); await Task.Delay(waitMs, ct); } } }参数怎么定refillPerSecond设成 1 到 2 之间比较稳妥capacity设成 3 到 5允许开头发几个请求把动态详情和第一页拿下来。这只是起点实际要看你账号的「耐受度」同一个值在不同网络环境下表现可能不一样。遇到风控就往下调调完重跑。除了令牌桶退避策略里加一点随机抖动也很有必要。纯指数退避1s、2s、4s、8s在多个进程同时跑的时候会形成同步脉冲反而更容易被识别。加个 ±30% 的随机偏移节奏就散了。4.3 异常分档可重试、不可重试与必须停机把所有异常一视同仁地重试是新手最常见的错误。有些错误重试一百次也没用有些错误重试会让情况变得更糟。我一般把异常分成三档写成一个分类函数让重试逻辑只负责执行决策。// 三档分类重试、直接失败、立即停机 private static RetryDecision Classify(HttpStatusCode status, int apiCode) { // 网络抖动与服务端 5xx可重试走指数退避 抖动 if (status HttpStatusCode.RequestTimeout || (int)status 500) return RetryDecision.RetryWithBackoff; // 风控与校验失败继续请求只会加重标记必须停下来换策略 if ((int)status 412 || apiCode -352 || apiCode -412) return RetryDecision.Halt; // 参数类错误动态 ID 错了、页码越界重试无意义 if (apiCode -400 || apiCode -404) return RetryDecision.Fail; return RetryDecision.RetryWithBackoff; }分档的意义在于止损。Halt这一档触发时程序应该把已经采集到的部分快照写盘再退出而不是直接抛异常。写过盘的数据至少还能用虽然不完整。这也是为什么采集逻辑要每页追加写一次而不是全部拉完再一次性写。顺便提一句 bilibili-tool 这个生态里通用的取舍多数同类工具选择不做自动重登录、不做多账号轮换因为它们会把复杂度拉高一个量级而抽奖这个场景对实时性要求不高——慢一点没关系别有遗漏。我认同这个取舍宁可慢不要脏数据。5. 避坑清单五类翻车现场的现象、成因与处置这一章是我自己踩过、也看别人踩过的坑按现象、原因、解决三段写。遇到问题先在这里对一遍多数情况能直接定位。5.1 抽出来的名单里有已经取关的人现象开奖结果公布后有人指出中奖者当前并未关注活动规则要求关注才能参与。原因关注状态是动态变化的。你在采集那一刻查到的是「已关注」但开奖时或者开奖后对方取关了。另一种可能是关注状态的判断依赖接口返回值而那个值有缓存延迟取关后一段时间内仍返回已关注。解决在开奖清单里记录每个中奖者的关注状态快照和采集时间明确写下「以采集时刻的状态为准」。如果活动规则严格可以在开奖前对中奖者做一次复核把已取关的剔除并按备选顺序补位。补位名单也一并存下来别现场重抽。5.2 转发列表少了一大截现象动态页面显示转发 3000 多脚本只拉到 900 条就结束了而且没有报错。原因三种可能。第一分页游标处理有误把某一页的游标当成结束信号第二触发了限速中间某几页返回空列表被当成了正常结束第三Cookie 在中途失效后续页全部返回空。解决先做对账——把动态详情里的转发总数和实际拉到的条数打出来差距超过 10% 直接判为采集失败。然后在分页循环里记录每页的返回条数出现「非最后一页却返回 0 条」就中断并报错而不是静默退出。限速参数按第 4 章的方法调低。Cookie 有效性在开始前先探测一次。5.3 名单里出现重复的 mid现象中奖名单里同一个人出现了两次或者参与者快照里有大量重复行。原因翻页期间数据前移导致同一 mid 在不同页被返回两次。如果只在最后一次性去重中间的所有统计数字都会偏大。解决在采集时就维护一个HashSetlong见第 3 章的代码。去重放在写入之前而不是分析阶段。另外注意昵称会改去重的键必须是 mid不能用昵称。5.4 跑到一半 412 或负数错误码程序直接崩现象采集到一半突然抛异常退出已经采的数据全在内存里什么都没留下。原因没有做异常分档所有异常都往上抛。同时没有做增量落盘程序一挂数据就丢。解决按第 4 章的三档分类处理遇到Halt就先落盘再优雅退出。采集循环里每页追加写一次文件虽然多几次 IO但比重头再来划算。退出时把最后成功处理的游标也写进去支持断点续采。5.5 时间窗对不上边界附近的参与者被误杀现象明明在活动时间内转发的用户被判定为「不在时间窗内」。原因配置里写的是本地时间接口返回的是另一个时区的时间戳比较时没有统一基准。跨零点的活动尤其容易出问题。解决配置文件里显式写带偏移的 ISO 8601 时间如08:00解析后立刻转 UTC全程用 UTC 比较。输出到名单里时再转回本地时间给人看。这个坑很隐蔽因为大多数时候只影响边界上的几十个人不专门核对根本发现不了。6. 让结果可复盘把一次开奖做成能查证的东西抽奖这个场景技术难度不高难的是「让人信」。一份名单发出去总有人问「是不是内定的」。与其解释不如让流程自带证据。我现在的习惯是每次开奖都产出一个清单文件把输入、随机种子、输出三样东西绑在一起谁有疑问就把清单发过去让他本地重跑一遍。清单里至少要有这几项动态 ID、参与者快照的文件名和它的哈希值、随机种子、中奖者 mid 列表、开奖时间、程序版本。前四项是复现所需的最小集合第五第六项用于追溯。// 开奖清单把输入、随机源、输出绑定成一个可校验的整体 var manifest new ResultManifest { DynamicId options.DynamicId, SnapshotFile participants.csv, SnapshotSha256 Sha256File(participants.csv), // 快照一旦被改动哈希对不上 RandomSeed options.Seed, WinnerCount winners.Count, Winners winners.Select(w w.Mid).ToArray(), ParticipantCount pool.Count, CreatedAt DateTimeOffset.UtcNow, ToolVersion typeof(ResultManifest).Assembly.GetName().Version?.ToString() }; File.WriteAllText( Path.Combine(options.OutDir, manifest.json), JsonSerializer.Serialize(manifest, new JsonSerializerOptions { WriteIndented true }));快照哈希这一项是核心。它的作用是证明「我事后没有改参与者名单」。别人拿到清单后用同名的快照文件算一遍哈希对得上就说明这份名单没被动过再用清单里的种子重跑一次得到的中奖者完全一致整条链路就闭环了。校验在命令行里做也简单不用写代码# 校验快照未被篡改结果应与 manifest.json 中的 SnapshotSha256 一致 sha256sum ./out/participants.csv # 用同一份快照和同一个种子重跑输出应与中奖名单完全一致 dotnet run --project ./src/BiliRaffle -- \ --from-snapshot ./out/participants.csv \ --seed 20241007 \ --winners 10 \ --out ./verify--from-snapshot这个参数是我最常用的一个。它跳过网络采集直接读本地快照跑过滤和开奖几秒钟出结果。规则改了、种子想换、中奖人数要调整全都可以离线试不用担心再碰接口。做活动复盘的时候这套离线能力比什么都实在。最后一个技巧关于人数超过候选池的情况。如果--winners设成 20而合格参与者只有 15 人程序会取全部 15 人并给出提示。这时候别急着改参数重跑先去看看过滤链是不是把太多人筛掉了——多数时候不是池子太小是规则配错了。从那以后我每次开奖都强制走一遍「先快照、再算哈希、离线复跑校验」的流程多花两分钟省掉的是后面一整晚的扯皮。希望你也能少走点弯路希望帮到你。本文还有配套的精品资源点击获取 BiliRaffle实战：B站动态抽奖的分页采集、限速与可复现开奖
简介BiliRaffle 是面向 B 站动态抽奖场景的 C# 开源桌面工具基于 .NET Framework 4.5 及以上运行适合希望直接使用抽奖功能或需要研究动态抽奖实现、进行二次开发的用户。压缩包共 32 个文件整体约 60KB以 12 个 cs 源码和 4 个 xaml 界面文件为核心另含 config、xml、dll、图标图片、解决方案及开源许可等结构紧凑覆盖登录、主界面、视图模型与抽奖逻辑等模块。现有 697 人学习说明其在 B 站工具类资源中具有一定关注度。读者可从中了解 C# 桌面端如何组织 MVVM 结构、接入 B 站相关接口、处理登录状态与抽奖流程也能据此排查依赖版本、运行环境和配置问题。代码围绕动态数据获取、条件筛选与结果展示形成较完整的小型工具链路适合作为源码阅读、功能拆解与二次改造的参考样例。1. 手动翻转发列表翻到眼花之后我把抽奖交给了 BiliRaffle一次活动动态挂了三天转发数冲到四位数负责发奖的同事从第一页翻到最后一页复制、粘贴、去重干了两个多小时最后名单里还混进几个早就取关的账号。这事之后我开始找能脚本化的方案翻到了 BiliRaffle——一个用 C# 写的 B 站动态抽奖组件。它做的事不玄学围绕 bilibili-api 把「取动态转发列表 → 校验参与资格 → 按 mid 去重 → 随机开奖 → 结果落盘」串成一条可重复执行的流程参数从命令行进结果从文件出。适合自己办小活动、需要一份能复盘的开奖记录的开发者也适合拿它当 bilibili-tool 学习样本、想看 C# 怎么封装带 Cookie 的分页接口的人不适合指望点两下就出结果的人后面几章会讲清门槛在哪。2. 先看懂骨架再动手BiliRaffle 的分层、调用链与首次跑通拿到一个 C# 组件最容易犯的错是直接dotnet run然后就着报错乱改。我一般的顺序是先把目录结构和调用链读一遍搞清楚哪一层负责发请求、哪一层负责判断规则、哪一层负责写文件再决定动哪里。BiliRaffle 的分层很薄几乎是为「一个脚本干一件事」这个目标裁出来的读起来不费劲但也意味着它不替你兜底——参数传错它会老老实实按错的方式跑完。2.1 三个目录扛下全部职责Api、Raffle 与 Output仓库里真正承担业务逻辑的只有三块剩下的都是胶水。我把它们和对应的关键类型列成表进场先对着这张表定位后面出问题基本能一眼看出该去看哪个文件。目录 / 文件职责边界典型类型Api/对 bilibili-api 的薄封装只负责组请求、带 Cookie、反序列化不含任何抽奖判断BiliApiClient、ApiResultTRaffle/参与者采集、过滤链、随机开奖纯内存计算不发请求ParticipantCollector、FilterChain、RaffleEngineOutput/参与者快照、中奖名单、开奖清单的序列化CsvWriter、ResultManifestProgram.cs命令行解析与依赖组装一行业务判断都不写CommandLineOptionsConfig/规则与限速参数的默认值RaffleRules、ThrottleOptions这个划分的直接好处是调接口出问题只看Api/抽出来的名单不对只看Raffle/文件格式不对只看Output/。很多同类小工具把三者揉在一个Main里几百行之后谁也不敢改这是我不太推荐的做法。Api/这层的设计取向值得单独说一句。它没有做通用 SDK不做签名、不做登录态刷新只接受一个已经拼好的 Cookie 字符串然后按接口路径发 GET。换句话说它把 bilibili-api 当成「一组需要鉴权的 HTTP 端点」来对待而不是当成一个有状态的客户端对象。这种薄封装在一次性抽奖场景里足够代价是所有鉴权细节都暴露给调用方Cookie 过期了它不会帮你换只会返回一个空列表或者一个错误码后面第 4 章会专门讲怎么识别。Raffle/里最需要注意的是FilterChain。它是有序执行的顺序不同结果可能不同。比如先按时间窗筛、再按关注状态筛和反过来做在网络抖动导致关注状态查不到时行为会有差别。仓库默认的顺序是先做本地就能判断的条件时间窗、是否重复、是否在自己维护的黑名单里再做需要额外请求的条件关注状态。这个顺序是有道理的把贵的判断放后面能省掉大量无效请求。Output/只有两个写入器一个写 CSV一个写 JSON 清单。CSV 给人看JSON 给校验用。这里有一个设计选择——写文件用的是覆盖而不是追加每次运行都会生成新的带时间戳的文件名。刚开始我觉得啰嗦后来发现这是好事你不会因为一次失败的重跑把上一次成功的快照冲掉。2.2 从 Cookie 到中奖名单一次抽奖走过的七个环节把整条链路摊平一次完整运行其实是七步。每一步都可能失败也都留下可观察的痕迹排错时按这个顺序往下捋比漫无目的地看日志快得多。解析命令行参数得到动态 ID、抽奖人数、规则配置文件路径、输出目录。用 Cookie 初始化 HTTP 客户端设置 UA 与超时。请求动态详情确认这条动态存在、是转发抽奖类型、当前状态可读。分页拉取转发列表逐页追加到内存列表同时记录每一页的游标。把原始参与者列表写成快照文件先落盘再过滤——这一步是后面所有争议的「后悔药」。按过滤链逐条判定得到合格参与者集合按 mid 去重。用随机引擎抽取 N 名中奖者写中奖名单和开奖清单。第三步容易被跳过我建议保留。动态详情里能拿到转发总数这个数字可以和第四步实际拉到的条数做交叉比对。如果详情说 3200 条转发你只拉到 800 条就结束了分页那一定是分页逻辑或限速出了问题此时抽出来的名单是不可信的。这种「先对账再开奖」的习惯是我踩过几次坑之后强制加进流程里的。第五步的「先落盘再过滤」同样是血泪经验。过滤规则是可以改的改完重跑一遍很快但如果你没留原始快照重跑就得重新拉一遍几千条转发既慢又可能因为接口波动拿到不一样的数据集。有了快照你甚至可以离线反复调整规则不用再碰网络。2.3 环境跑通.NET SDK、还原依赖与第一条命令环境部分没有太多花样C# 项目对环境的要求就是 SDK 版本对得上。我一般用当前 LTS 版本的 .NET SDK版本太老会在还原阶段就因为语言特性报错。先确认环境再还原最后才跑。# 确认 SDK 版本低于项目 TargetFramework 会在还原阶段直接报错 dotnet --info # 还原依赖这一步只走 NuGet不涉及任何接口调用 dotnet restore ./BiliRaffle.sln # 编译先保证能编过再谈运行 dotnet build ./BiliRaffle.sln -c Release --no-restore编译通过之后再跑第一次。第一次不要直接抽奖先用「只采集不开奖」的模式把参与者拉下来看看数量对不对。# --dry-run 只采集与过滤不执行开奖输出参与者快照 dotnet run --project ./src/BiliRaffle -- \ --dynamic-id 123456789012345678 \ --cookie $BILI_COOKIE \ --winners 1 \ --rules ./config/rules.json \ --out ./out \ --dry-run参数逐个说清楚这几个是最常改的--dynamic-id动态 ID从动态链接里取数字部分。注意不是用户 UID两者长度和含义都不同传错会得到一个「动态不存在」的返回。--cookie完整 Cookie 字符串从浏览器开发者工具里整段复制。这里用环境变量传入是为了避免它被写进 shell 历史和提交记录。--winners中奖人数。超过合格参与者数量时不同实现行为不同BiliRaffle 的做法是取全部并给出提示不会补位重抽。--rules规则配置路径不传就用内置默认值。默认值通常偏宽松正式活动建议显式传。--out输出目录不存在会自动创建同一秒内重复运行会覆盖同名文件。--dry-run只采集不开奖。第一次运行强烈建议带上先看参与者数量是否和动态页面上显示的转发数对得上。--dry-run跑完out/下应该出现一个带时间戳的参与者 CSV。打开它看三件事行数、表头、有没有明显的重复 mid。行数对不上就先别往下走去第 5 章找对应的排查条目。3. 把规则写进代码参与资格过滤、分页快照与开奖算法规则这块是整个组件里最容易被低估的部分。很多人以为抽奖就是Random.Next一下实际上真正决定结果可信度的是「谁进了候选池」。候选池错了随机算法再漂亮也没意义。BiliRaffle 把规则拆成可组合的过滤器这个设计我认为是对的因为活动规则每次都不一样硬编码进去必然要改代码。3.1 四类过滤器关注状态、转发时间窗、 数量与黑名单过滤器在代码里是一个很小的接口每个实现只回答一个问题这个人算不算合格参与者。不合格时给出原因字符串方便后面统计「被筛掉的人分别因为什么」。// 每个过滤器只做一个判断返回 false 时带上原因便于事后统计 public interface IParticipantFilter { bool Accept(Participant p, RaffleContext ctx, out string reason); } // 时间窗过滤只认活动开始时间之后、截止时间之前的转发 public sealed class TimeWindowFilter : IParticipantFilter { private readonly DateTimeOffset _from; private readonly DateTimeOffset _to; public TimeWindowFilter(DateTimeOffset from, DateTimeOffset to) { _from from; _to to; } public bool Accept(Participant p, RaffleContext ctx, out string reason) { // 转发时间统一用 UTC 比较避免本地时区带来的跨天误差 if (p.ForwardTime _from || p.ForwardTime _to) { reason out_of_window; return false; } reason string.Empty; return true; } }TimeWindowFilter里那个 UTC 比较不是多余的。活动配置里写的是「10 月 1 日 00:00 到 10 月 7 日 23:59」如果按本地时间解析、按接口返回的时间戳比较中间就会差出几个小时边界上的参与者会被误杀或者误放进来。我一般的做法是配置文件里显式带时区偏移解析后立刻转 UTC全程不再碰本地时间。另外三个过滤器分别是关注状态、 数量和黑名单。关注状态需要额外请求所以放在过滤链靠后的位置 数量取决于你对活动规则的定义有的活动要求 一位好友有的不要求这个只能按活动实际情况配黑名单是纯本地列表用来排除已知的异常账号或者内部人员跑在第一位最省请求。过滤链的顺序写在配置里不在代码里这一点很重要。活动规则变了改配置就行不用重新编译。{ rules: { filters: [blacklist, timeWindow, atCount, following], from: 2024-10-01T00:00:0008:00, to: 2024-10-07T23:59:5908:00, minAtCount: 1, requireFollowing: true } }配置里的filters数组就是执行顺序。把following放最后是因为它是唯一需要发请求的一环前面的本地过滤能砍掉多少人就砍掉多少人。3.2 分页快照为什么必须先把参与者全量落盘再抽奖分页拉取这件事表面上是个循环实际藏着三个坑游标什么时候算结束、单页返回空是不是真的没了、翻页过程中的数据变动怎么处理。先说结束条件。很多接口在最后一页会返回一个空列表但也有一些会在最后一页返回一个不满的列表而不是空列表。如果你的循环条件是「返回条数小于页大小就停」遇到前者会多请求一次遇到后者会正常结束。如果你的条件是「返回空就停」那遇到后者就会漏掉最后一页。稳妥的写法是两个条件都判并且加一个最大页数上限兜底防止因为接口异常导致死循环。再说翻页过程中的变动。抽奖活动进行中转发数是在实时增长的。你从第一页翻到最后一页可能要几十秒这期间新进来的转发会插在列表前面导致你翻到后面时前面已经翻过的位置内容整体后移出现重复或者跳过。这个问题没有完美解因为接口不提供一致性快照。能做的是翻完之后按 mid 去重并且记录一个采集起止时间在开奖说明里写清楚「以某时刻采集到的转发列表为准」。所以快照这一步不只是「留个备份」它是整个流程的事实基准。我的习惯是快照文件用participants-{dynamicId}-{timestamp}.csv命名字段至少包含 mid、昵称、转发时间、原始页码。// 采集结果先写盘再进入过滤保证任何一次开奖都能追溯到原始数据集 public sealed class ParticipantCollector { private readonly BiliApiClient _api; private readonly int _pageSize; public ParticipantCollector(BiliApiClient api, int pageSize 20) { _api api; _pageSize pageSize; } public async TaskIReadOnlyListParticipant CollectAsync( long dynamicId, int maxPages, CancellationToken ct) { var all new ListParticipant(); var seen new HashSetlong(); string? cursor null; for (int page 0; page maxPages; page) { // 每页之间由限速器控制节奏不在循环里手动 sleep var result await _api.GetRepostPageAsync(dynamicId, cursor, _pageSize, ct); if (!result.IsSuccess || result.Items.Count 0) break; foreach (var item in result.Items) { // 翻页期间数据会前移同一 mid 可能被重复返回 if (seen.Add(item.Mid)) all.Add(item); } cursor result.NextCursor; if (string.IsNullOrEmpty(cursor)) break; // 游标为空表示到底 } return all; } }代码里三个细节值得单独点出来。seen这个 HashSet 同时承担去重和终止判断——如果某一页返回的条目全部是已见过的说明已经在原地打转可以直接停。maxPages是个保险丝按「预估转发数 / 页大小 × 2」估算超了就是异常。游标为空作为结束信号比「返回条数小于页大小」更可靠前提是接口确实返回了游标。3.3 开奖随机性Fisher-Yates 与可复现的随机种子随机这块Random.Next直接在列表里取 N 次是不能用的因为会取到重复。正确的做法是先洗牌再取前 N 个洗牌用 Fisher-Yates复杂度 O(n)结果均匀。// Fisher-Yates 洗牌每个排列等概率取前 n 个即为不重复的随机中奖者 public static IReadOnlyListT ShuffleT(IReadOnlyListT source, Random rng) { var buffer source.ToArray(); for (int i buffer.Length - 1; i 0; i--) { int j rng.Next(i 1); (buffer[i], buffer[j]) (buffer[j], buffer[i]); } return buffer; } // 开奖入口种子显式传入便于事后复现同一份名单 public IReadOnlyListParticipant Draw( IReadOnlyListParticipant pool, int count, int seed) { var rng new Random(seed); return Shuffle(pool, rng).Take(Math.Min(count, pool.Count)).ToList(); }seed为什么不让它自动生成因为抽奖这件事天然会被质疑。有了显式种子和参与者快照任何人都能在本地用同一个种子重跑一遍得到完全一致的中奖名单。这是最有力的自证方式比截图有用得多。种子本身可以公开它不是秘密只是复现的钥匙。bilibili-raffle 类的工具在这块常见的分歧是「要不要给参与者加权」。我的看法是除非活动规则里明确写了加权比如连续转发多天加权否则一律等概率。加权会引入一堆解释成本而且权重配置一旦出错很难被发现。4. 接口这头的现实问题Cookie 生命周期、限速与异常分档本地逻辑写得再干净跑起来还是会被接口教做人。这一章讲三个必然会遇到的东西Cookie 什么时候失效、请求发多快算合适、报错之后该重试还是该停。4.1 Cookie 三件套与失效的三种表现B 站的登录态 Cookie 里真正决定能不能拿到数据的通常是三个字段一个标识会话、一个用于校验、一个标识用户 ID。BiliRaffle 不做登录流程它只是把整段 Cookie 塞进请求头所以这三个字段必须由你自己从浏览器里取而且要取全。少一个的表现各不相同少会话字段通常直接返回未登录少校验字段在只读接口上可能还能用但一旦触发需要校验的路径就失败少用户 ID 字段有时候能读到公开数据但读不到需要身份的字段。失效的表现有三种区分清楚能省很多时间第一种是直接返回未登录错误码这种最好处理换 Cookie 重跑。 第二种是返回空列表HTTP 状态是 200看起来一切正常。这种最坑因为你的流程会「成功」跑完只是参与者数量是 0。所以第 2 章里强调的「先对账」在这里就派上用场了。 第三种是触发风控返回 412 或者一个特定的负数错误码。这种通常不是 Cookie 本身过期而是请求特征异常比如频率太高、UA 不对、短时间内换了 IP 段。我的习惯是拿到 Cookie 之后先跑一次最小的探测请求比如读自己的用户信息确认身份有效再开始正式采集。这一步几十毫秒能避免后面几千条数据白拉。4.2 限速器怎么写令牌桶与抖动退避限速不是「每页 sleep 一秒」这么简单。固定 sleep 的问题是如果一次请求本身花了 800 毫秒你实际间隔是 1.8 秒浪费如果请求很快返回间隔又变成 1 秒节奏不均。更合理的做法是令牌桶控制的是长期平均速率允许一定程度的突发。// 令牌桶capacity 控制突发refillPerSecond 控制长期平均 QPS public sealed class TokenBucket { private readonly double _capacity; private readonly double _refillPerSecond; private double _tokens; private DateTimeOffset _lastRefill; public TokenBucket(double capacity, double refillPerSecond) { _capacity capacity; _refillPerSecond refillPerSecond; _tokens capacity; _lastRefill DateTimeOffset.UtcNow; } public async Task WaitAsync(CancellationToken ct) { while (true) { var now DateTimeOffset.UtcNow; var elapsed (now - _lastRefill).TotalSeconds; _tokens Math.Min(_capacity, _tokens elapsed * _refillPerSecond); _lastRefill now; if (_tokens 1) { _tokens - 1; return; } // 按缺口时长精确等待而不是固定 sleep 一整秒 var waitMs (int)Math.Ceiling((1 - _tokens) / _refillPerSecond * 1000); await Task.Delay(waitMs, ct); } } }参数怎么定refillPerSecond设成 1 到 2 之间比较稳妥capacity设成 3 到 5允许开头发几个请求把动态详情和第一页拿下来。这只是起点实际要看你账号的「耐受度」同一个值在不同网络环境下表现可能不一样。遇到风控就往下调调完重跑。除了令牌桶退避策略里加一点随机抖动也很有必要。纯指数退避1s、2s、4s、8s在多个进程同时跑的时候会形成同步脉冲反而更容易被识别。加个 ±30% 的随机偏移节奏就散了。4.3 异常分档可重试、不可重试与必须停机把所有异常一视同仁地重试是新手最常见的错误。有些错误重试一百次也没用有些错误重试会让情况变得更糟。我一般把异常分成三档写成一个分类函数让重试逻辑只负责执行决策。// 三档分类重试、直接失败、立即停机 private static RetryDecision Classify(HttpStatusCode status, int apiCode) { // 网络抖动与服务端 5xx可重试走指数退避 抖动 if (status HttpStatusCode.RequestTimeout || (int)status 500) return RetryDecision.RetryWithBackoff; // 风控与校验失败继续请求只会加重标记必须停下来换策略 if ((int)status 412 || apiCode -352 || apiCode -412) return RetryDecision.Halt; // 参数类错误动态 ID 错了、页码越界重试无意义 if (apiCode -400 || apiCode -404) return RetryDecision.Fail; return RetryDecision.RetryWithBackoff; }分档的意义在于止损。Halt这一档触发时程序应该把已经采集到的部分快照写盘再退出而不是直接抛异常。写过盘的数据至少还能用虽然不完整。这也是为什么采集逻辑要每页追加写一次而不是全部拉完再一次性写。顺便提一句 bilibili-tool 这个生态里通用的取舍多数同类工具选择不做自动重登录、不做多账号轮换因为它们会把复杂度拉高一个量级而抽奖这个场景对实时性要求不高——慢一点没关系别有遗漏。我认同这个取舍宁可慢不要脏数据。5. 避坑清单五类翻车现场的现象、成因与处置这一章是我自己踩过、也看别人踩过的坑按现象、原因、解决三段写。遇到问题先在这里对一遍多数情况能直接定位。5.1 抽出来的名单里有已经取关的人现象开奖结果公布后有人指出中奖者当前并未关注活动规则要求关注才能参与。原因关注状态是动态变化的。你在采集那一刻查到的是「已关注」但开奖时或者开奖后对方取关了。另一种可能是关注状态的判断依赖接口返回值而那个值有缓存延迟取关后一段时间内仍返回已关注。解决在开奖清单里记录每个中奖者的关注状态快照和采集时间明确写下「以采集时刻的状态为准」。如果活动规则严格可以在开奖前对中奖者做一次复核把已取关的剔除并按备选顺序补位。补位名单也一并存下来别现场重抽。5.2 转发列表少了一大截现象动态页面显示转发 3000 多脚本只拉到 900 条就结束了而且没有报错。原因三种可能。第一分页游标处理有误把某一页的游标当成结束信号第二触发了限速中间某几页返回空列表被当成了正常结束第三Cookie 在中途失效后续页全部返回空。解决先做对账——把动态详情里的转发总数和实际拉到的条数打出来差距超过 10% 直接判为采集失败。然后在分页循环里记录每页的返回条数出现「非最后一页却返回 0 条」就中断并报错而不是静默退出。限速参数按第 4 章的方法调低。Cookie 有效性在开始前先探测一次。5.3 名单里出现重复的 mid现象中奖名单里同一个人出现了两次或者参与者快照里有大量重复行。原因翻页期间数据前移导致同一 mid 在不同页被返回两次。如果只在最后一次性去重中间的所有统计数字都会偏大。解决在采集时就维护一个HashSetlong见第 3 章的代码。去重放在写入之前而不是分析阶段。另外注意昵称会改去重的键必须是 mid不能用昵称。5.4 跑到一半 412 或负数错误码程序直接崩现象采集到一半突然抛异常退出已经采的数据全在内存里什么都没留下。原因没有做异常分档所有异常都往上抛。同时没有做增量落盘程序一挂数据就丢。解决按第 4 章的三档分类处理遇到Halt就先落盘再优雅退出。采集循环里每页追加写一次文件虽然多几次 IO但比重头再来划算。退出时把最后成功处理的游标也写进去支持断点续采。5.5 时间窗对不上边界附近的参与者被误杀现象明明在活动时间内转发的用户被判定为「不在时间窗内」。原因配置里写的是本地时间接口返回的是另一个时区的时间戳比较时没有统一基准。跨零点的活动尤其容易出问题。解决配置文件里显式写带偏移的 ISO 8601 时间如08:00解析后立刻转 UTC全程用 UTC 比较。输出到名单里时再转回本地时间给人看。这个坑很隐蔽因为大多数时候只影响边界上的几十个人不专门核对根本发现不了。6. 让结果可复盘把一次开奖做成能查证的东西抽奖这个场景技术难度不高难的是「让人信」。一份名单发出去总有人问「是不是内定的」。与其解释不如让流程自带证据。我现在的习惯是每次开奖都产出一个清单文件把输入、随机种子、输出三样东西绑在一起谁有疑问就把清单发过去让他本地重跑一遍。清单里至少要有这几项动态 ID、参与者快照的文件名和它的哈希值、随机种子、中奖者 mid 列表、开奖时间、程序版本。前四项是复现所需的最小集合第五第六项用于追溯。// 开奖清单把输入、随机源、输出绑定成一个可校验的整体 var manifest new ResultManifest { DynamicId options.DynamicId, SnapshotFile participants.csv, SnapshotSha256 Sha256File(participants.csv), // 快照一旦被改动哈希对不上 RandomSeed options.Seed, WinnerCount winners.Count, Winners winners.Select(w w.Mid).ToArray(), ParticipantCount pool.Count, CreatedAt DateTimeOffset.UtcNow, ToolVersion typeof(ResultManifest).Assembly.GetName().Version?.ToString() }; File.WriteAllText( Path.Combine(options.OutDir, manifest.json), JsonSerializer.Serialize(manifest, new JsonSerializerOptions { WriteIndented true }));快照哈希这一项是核心。它的作用是证明「我事后没有改参与者名单」。别人拿到清单后用同名的快照文件算一遍哈希对得上就说明这份名单没被动过再用清单里的种子重跑一次得到的中奖者完全一致整条链路就闭环了。校验在命令行里做也简单不用写代码# 校验快照未被篡改结果应与 manifest.json 中的 SnapshotSha256 一致 sha256sum ./out/participants.csv # 用同一份快照和同一个种子重跑输出应与中奖名单完全一致 dotnet run --project ./src/BiliRaffle -- \ --from-snapshot ./out/participants.csv \ --seed 20241007 \ --winners 10 \ --out ./verify--from-snapshot这个参数是我最常用的一个。它跳过网络采集直接读本地快照跑过滤和开奖几秒钟出结果。规则改了、种子想换、中奖人数要调整全都可以离线试不用担心再碰接口。做活动复盘的时候这套离线能力比什么都实在。最后一个技巧关于人数超过候选池的情况。如果--winners设成 20而合格参与者只有 15 人程序会取全部 15 人并给出提示。这时候别急着改参数重跑先去看看过滤链是不是把太多人筛掉了——多数时候不是池子太小是规则配错了。从那以后我每次开奖都强制走一遍「先快照、再算哈希、离线复跑校验」的流程多花两分钟省掉的是后面一整晚的扯皮。希望你也能少走点弯路希望帮到你。本文还有配套的精品资源点击获取