Gitea 前端开发指南Vue 3 与 Go 模板混排的架构、编码规范与 fetch-action 请求框架【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea本文基于 Gitea 仓库的 前端开发规范文档 展开系统讲解 Gitea 前端“Go HTML 模板 Vue 3 硬分叉 Fomantic-UI Tailwind CSS”的多层技术栈如何组织逐条解读 Gitea 特有的命名、CSS、TypeScript 与 DOM 操作约定并结合仓库源码深入剖析fetch.ts请求封装与fetch-action声明式请求框架的实现机制。读完后你将掌握在 Gitea 前端中新增功能、提交表单、操作 DOM 的标准做法与底层原理。一、总体架构四层前端技术如何共存Gitea 的前端并不是单一框架的纯血实现而是四种技术协同工作的混合体引自 guidelines-frontend.mdVue 3负责复杂、强交互的页面组件Fomantic-UI基于 jQuery 的 UI 框架。Gitea 对其做了硬分叉hard-fork并 vendored 了一个经过大量修改的特定版本处于逐步弃用状态Tailwind CSS以工具类方式提供原子化样式Go HTML 模板负责所有页面的服务端渲染。这些技术栈的存在可以从 package.json 中得到印证vue: 3.5.41、tailwindcss: 3.4.19、jquery: 4.0.0供 Fomantic 使用、eslint-plugin-vue与vue-tscVue 工具链而页面 HTML 则由 Go 侧的 templates/ 目录提供。源码目录布局前端源码集中在以下几个目录这也是规范文档明确列出的结构目录职责web_src/css/CSS 样式web_src/js/JavaScript 与 TypeScript 源码web_src/js/components/Vue 组件web_src/js/features/页面加载时挂载的功能模块templates/Go HTML 模板从构建配置看vite.config.tsVite 以web_src/js/index.ts为主入口另构建swagger、external-render-frontend、user-events.sharedworker、devtest开发用 UI 组件画廊样式以及各主题 CSS 等独立入口产物输出到public/assets并生成manifest.json。开发模式下 Vite dev server 默认监听 3001 端口通过端口文件让 Go 服务器发现并代理见 vite.config.ts这也是appType: custom的原因——所有 HTML 都由 Go 服务Vite 不处理 HTML。二、依赖管理pnpm 与“只引用已发布版本”前端依赖统一由pnpm管理。package.json 中声明了packageManager: pnpm11.22.0engines要求node 22.18.0、pnpm 11.0.0。规范文档规定前端依赖遵循与后端依赖相同的治理规则只是相关文件换成了package.json和 pnpm-lock.yaml并且有一条硬性要求新版本号必须始终引用一个已发布的现存版本published version——不允许在 lockfile 里锁定尚未正式发布的构建。构建侧对应 Makefile 的frontend目标约 L493它调用 Vite 完成 CSS/JS 产物生成生产构建还会经过 vite.config.ts 中的licensePlugin把 Go 侧与 npm 侧的开源许可文本合并输出为licenses.txt并要求许可证属于允许清单Apache-2.0、MIT、BSD 等。三、框架使用推荐组合与明确红线规范文档的核心立场是随意混搭框架会让代码难以维护。推荐的技术组合只有三种Vue 3复杂交互原生 JavaScriptFomantic-UIjQuery——已弃用但仍是大量存量代码的视觉与行为基础。由此衍生的几条红线避免 Vue 与 Fomantic-UI 混用在同一个组件里但Vue 组件可以复用 Fomantic-UI 的 CSS 类来保证视觉一致简单页面或与 SEO 相关的页面用 Go 模板渲染复杂交互页面才上 VueGitea 使用 Vue 3 且刻意不使用 JSX让 HTML 与 JavaScript 保持分离可访问性提示Fomantic-UI 并非对辅助功能友好的框架Gitea 只是修补了部分 ARIA 行为可访问性建设仍在进行中——应优先使用语义化 HTML并在可行处测试键盘/读屏器行为。四、Gitea 特有编码约定以下是 guidelines-frontend.md 列出的项目级约定每一条都直接影响代码评审结果功能自包含每个功能放在自己的文件或目录中避免巨型杂烩模块命名规则HTML 的id和 class 使用kebab-case且只带 2~3 个描述功能的关键词类名前缀为类加前缀避免不同框架间短名称冲突.field自动关联Fomantic 框架可以自动关联作为.field元素子节点的input与label因此通常不需要写id/for属性除非有特定理由样式覆盖方式覆盖框架样式时新建一个类名而不是直接改框架自己的类如果要根治则去修框架源码以覆盖所有场景语义化优先优先用button等语义元素而不是泛泛的div慎用!important必须使用时要写明理由自定义 DOM 事件加ce-前缀与浏览器原生事件和其他库的事件区分开。五、CSS 体系tw-、gt-、g-三套前缀的分工Gitea 的 CSS 约定可以概括为三层Tailwind 工具类前缀tw-优先用flex-*布局辅助类而不是给每个子元素手写 margingt-前缀Gitea 的 Tailwind 风格通用辅助类g-前缀框架级私有样式辅助类。gt-与g-的定义集中放在 web_src/css/helpers.css文件头部注释即写明/* Giteas tailwind-style CSS helper classes have gt- prefix. Giteas private styles use g- prefix. */其中包含.gt-ellipsis单行省略、.not-mobile/.only-mobile按 767.98px 断点显隐、.tab-size-*系列、.interact-fg/.interact-bg交互态颜色等。只有在 Tailwind 没有对应工具类时才使用这些自定义辅助类。Tailwind 的关键配置tailwind.config.ts 揭示了若干与“多框架混排”直接相关的设计决策prefix: tw-所有工具类强制加前缀避免与 Fomantic 类名撞车important: true注释写明“框架混在一起Tailwind 需要能覆盖其他框架的样式”blocklist中移除了原生hidden因为Gitea 用双类名.tw-hidden获得更高优先级见下方插件自定义插件中定义了.hidden.hidden { display: none }即tw-hidden.tw-hidden并逐条注释了为什么不能用[hidden]属性打不过display: flex、不能用原生.hidden被 Fomantic 污染、不能用内联styledisplay:none难以微调、也不能用 jQuery 的 show/hide/toggle对display: xxx !important无效content扫描范围不仅包含模板与前端源码还包含build/models/modules/routers/services下的.go文件——因为 Go 代码中包括测试文件也会出现class...字符串Tailwind 需要据此生成类颜色 token如tw-bg-primary来自 web_src/css/themes/theme-gitea-light.css 与theme-gitea-dark.css中:root定义的--color-*CSS 变量由构建时自动抽取tailwind.config.ts因此暗色主题切换无需重编译样式。模板中的 class 书写方式规范要求在模板中把 class 属性写成一个可整体阅读的单位例如div classflex-text-inline {{if .IsFoo}}tw-hidden{{end}}/div而不是把条件类拆分到多处拼接。六、TypeScript 风格规则guidelines-frontend.md 对 TypeScript 给出三条明确规则类型导入一律用import type已知必然存在的值用!非空断言而不是用?./??掩盖确定的事实例如 fetch-action.ts 中el.getAttribute(data-url)!的写法就是这一约定的体现函数只有真正await或返回Promise才标记async避免异步事件监听器无法避免时必须在第一个await之前调用e.preventDefault()——否则默认行为如表单提交、链接跳转会在异步回调执行前抢先发生。七、数据获取fetch.ts 封装与 fetch-action 框架7.1 底层封装web_src/js/modules/fetch.ts规范明确要求不要直接使用裸fetch而是使用web_src/js/modules/fetch.ts导出的GET、POST、PUT、PATCH、DELETE包装函数。该文件只有 33 行核心逻辑是export function request(url: string, {method GET, data, headers {}, ...other}: RequestOpts {}): PromiseResponse { let body: string | FormData | URLSearchParams | undefined; let contentType: string | undefined; if (data instanceof FormData || data instanceof URLSearchParams) { body data; } else if (isObject(data) || Array.isArray(data)) { contentType application/json; body JSON.stringify(data); } headers new Headers(headers); if (!headers.has(content-type) contentType) { headers.set(content-type, contentType); } return fetch(url, {method, headers, ...other, ...(body {body})}); } export const GET (url: string, opts?: RequestOpts) request(url, {method: GET, ...opts}); export const POST (url: string, opts?: RequestOpts) request(url, {method: POST, ...opts}); // PATCH / PUT / DELETE 同理它的价值在于把data选项统一转换为请求体——FormData/URLSearchParams原样透传浏览器自动设置正确的Content-Type普通对象/数组则自动JSON.stringify并设置application/json头调用方无需关心序列化细节。文件顶部注释也说明这是 eslint 规则中唯一被豁免使用裸fetch的位置。7.2 声明式请求框架web_src/js/modules/fetch-action.ts对于表单提交、按钮点击和一般网络请求规范推荐优先使用 web_src/js/modules/fetch-action.ts 框架理由是它提供一致的 UX 与错误处理。从源码看initGlobalFetchAction这是一套“类 HTMX”的声明式系统元素上的属性即行为配置属性含义data-fetch-url请求目标 URLdata-fetch-methodHTTP 方法。fetch 触发默认GETlink-action元素默认POST表单则忽略该属性以表单method为准缺省GETdata-fetch-trigger触发时机click、change用户触发、load页面加载、every 5s定时也支持ms单位、fetch-reload仅在 fetch-sync 成功后由内部触发用于刷新过时内容data-fetch-indicator加载指示元素选择器语法与data-fetch-sync相同用户触发默认$this元素自身按钮会直接disabled其他元素加is-loading类data-fetch-sync响应为 HTML 时的页面更新伪选择器命令见下data-modal-confirm动作前弹出确认框可以是提示文本也可以是#modal-id引用已有模态框并支持-header、-content变体两个开箱即用的语义化 class.link-actiona classlink-action>export function toggleElem(el: ElementArg, force?: boolean): ArrayLikeIterableElement { return toggleElemClass(el, tw-hidden, force undefined ? force : !force); } export function showElem(el: ElementArg) { return toggleElem(el, true); } export function hideElem(el: ElementArg) { return toggleElem(el, false); }这与 tailwind.config.ts 的注释是配套的.tw-hidden双类名提权必须能压过一切display: xxx !important是 Gitea 中唯一被认可的隐藏手段。九、UI 组件画廊/devtest 页面开发模式下Gitea 提供标准化的UI 组件画廊访问/devtest如http://localhost:3000/devtest集中预览各类组件的当前渲染效果这些页面同时被 e2e 测试复用tests/e2e/。从源码看该路由组定义在 routers/web/web.gom.Group(/devtest, ...)处理器位于 routers/web/devtest/ 包devtest.go 的List会遍历 templates/devtest/ 目录列出所有组件模板页如form-fields、fomantic-dropdown、toast-and-message、relative-time等TmplCommon按{sub}参数渲染对应模板此外还提供fetch-action-test、mail-preview以及 Actions 运行视图的 mock 数据mock_actions.go等专门测试端点。这构成了一条“改样式/组件 → 在/devtest目检 → e2e 自动回归”的闭环是验证前端改动的第一现场。十、小结Gitea 的前端规范本质上是一套“在框架混排中维持秩序”的工程约定架构上Go 模板保底简单/SEO 页面Vue 3无 JSX承接复杂交互Fomantic-UI 存量维护并逐步退出命名上tw-/gt-/g-/ce-等前缀体系与 kebab-case 约束杜绝了跨框架命名污染数据流上fetch.ts统一请求序列化fetch-action以声明式属性接管“确认 → 加载指示 → 请求 → 错误 toast/字段标红 → 局部更新/跳转”的完整链路工程上pnpm 锁定已发布版本Tailwind 扫描 Go 源码与模板/devtest组件画廊与 e2e 测试共同保障 UI 回归。遵循 docs/guidelines-frontend.md 的上述约定再配合 docs/CONTRIBUTING.md 对应的工作流、docs/development.md 的构建方式与 docs/testing.md 的测试要求即可在 Gitea 前端中安全、规范地开展开发。【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gitea 前端开发指南：Vue 3 与 Go 模板混排的架构、编码规范与 fetch-action 请求框架
Gitea 前端开发指南Vue 3 与 Go 模板混排的架构、编码规范与 fetch-action 请求框架【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea本文基于 Gitea 仓库的 前端开发规范文档 展开系统讲解 Gitea 前端“Go HTML 模板 Vue 3 硬分叉 Fomantic-UI Tailwind CSS”的多层技术栈如何组织逐条解读 Gitea 特有的命名、CSS、TypeScript 与 DOM 操作约定并结合仓库源码深入剖析fetch.ts请求封装与fetch-action声明式请求框架的实现机制。读完后你将掌握在 Gitea 前端中新增功能、提交表单、操作 DOM 的标准做法与底层原理。一、总体架构四层前端技术如何共存Gitea 的前端并不是单一框架的纯血实现而是四种技术协同工作的混合体引自 guidelines-frontend.mdVue 3负责复杂、强交互的页面组件Fomantic-UI基于 jQuery 的 UI 框架。Gitea 对其做了硬分叉hard-fork并 vendored 了一个经过大量修改的特定版本处于逐步弃用状态Tailwind CSS以工具类方式提供原子化样式Go HTML 模板负责所有页面的服务端渲染。这些技术栈的存在可以从 package.json 中得到印证vue: 3.5.41、tailwindcss: 3.4.19、jquery: 4.0.0供 Fomantic 使用、eslint-plugin-vue与vue-tscVue 工具链而页面 HTML 则由 Go 侧的 templates/ 目录提供。源码目录布局前端源码集中在以下几个目录这也是规范文档明确列出的结构目录职责web_src/css/CSS 样式web_src/js/JavaScript 与 TypeScript 源码web_src/js/components/Vue 组件web_src/js/features/页面加载时挂载的功能模块templates/Go HTML 模板从构建配置看vite.config.tsVite 以web_src/js/index.ts为主入口另构建swagger、external-render-frontend、user-events.sharedworker、devtest开发用 UI 组件画廊样式以及各主题 CSS 等独立入口产物输出到public/assets并生成manifest.json。开发模式下 Vite dev server 默认监听 3001 端口通过端口文件让 Go 服务器发现并代理见 vite.config.ts这也是appType: custom的原因——所有 HTML 都由 Go 服务Vite 不处理 HTML。二、依赖管理pnpm 与“只引用已发布版本”前端依赖统一由pnpm管理。package.json 中声明了packageManager: pnpm11.22.0engines要求node 22.18.0、pnpm 11.0.0。规范文档规定前端依赖遵循与后端依赖相同的治理规则只是相关文件换成了package.json和 pnpm-lock.yaml并且有一条硬性要求新版本号必须始终引用一个已发布的现存版本published version——不允许在 lockfile 里锁定尚未正式发布的构建。构建侧对应 Makefile 的frontend目标约 L493它调用 Vite 完成 CSS/JS 产物生成生产构建还会经过 vite.config.ts 中的licensePlugin把 Go 侧与 npm 侧的开源许可文本合并输出为licenses.txt并要求许可证属于允许清单Apache-2.0、MIT、BSD 等。三、框架使用推荐组合与明确红线规范文档的核心立场是随意混搭框架会让代码难以维护。推荐的技术组合只有三种Vue 3复杂交互原生 JavaScriptFomantic-UIjQuery——已弃用但仍是大量存量代码的视觉与行为基础。由此衍生的几条红线避免 Vue 与 Fomantic-UI 混用在同一个组件里但Vue 组件可以复用 Fomantic-UI 的 CSS 类来保证视觉一致简单页面或与 SEO 相关的页面用 Go 模板渲染复杂交互页面才上 VueGitea 使用 Vue 3 且刻意不使用 JSX让 HTML 与 JavaScript 保持分离可访问性提示Fomantic-UI 并非对辅助功能友好的框架Gitea 只是修补了部分 ARIA 行为可访问性建设仍在进行中——应优先使用语义化 HTML并在可行处测试键盘/读屏器行为。四、Gitea 特有编码约定以下是 guidelines-frontend.md 列出的项目级约定每一条都直接影响代码评审结果功能自包含每个功能放在自己的文件或目录中避免巨型杂烩模块命名规则HTML 的id和 class 使用kebab-case且只带 2~3 个描述功能的关键词类名前缀为类加前缀避免不同框架间短名称冲突.field自动关联Fomantic 框架可以自动关联作为.field元素子节点的input与label因此通常不需要写id/for属性除非有特定理由样式覆盖方式覆盖框架样式时新建一个类名而不是直接改框架自己的类如果要根治则去修框架源码以覆盖所有场景语义化优先优先用button等语义元素而不是泛泛的div慎用!important必须使用时要写明理由自定义 DOM 事件加ce-前缀与浏览器原生事件和其他库的事件区分开。五、CSS 体系tw-、gt-、g-三套前缀的分工Gitea 的 CSS 约定可以概括为三层Tailwind 工具类前缀tw-优先用flex-*布局辅助类而不是给每个子元素手写 margingt-前缀Gitea 的 Tailwind 风格通用辅助类g-前缀框架级私有样式辅助类。gt-与g-的定义集中放在 web_src/css/helpers.css文件头部注释即写明/* Giteas tailwind-style CSS helper classes have gt- prefix. Giteas private styles use g- prefix. */其中包含.gt-ellipsis单行省略、.not-mobile/.only-mobile按 767.98px 断点显隐、.tab-size-*系列、.interact-fg/.interact-bg交互态颜色等。只有在 Tailwind 没有对应工具类时才使用这些自定义辅助类。Tailwind 的关键配置tailwind.config.ts 揭示了若干与“多框架混排”直接相关的设计决策prefix: tw-所有工具类强制加前缀避免与 Fomantic 类名撞车important: true注释写明“框架混在一起Tailwind 需要能覆盖其他框架的样式”blocklist中移除了原生hidden因为Gitea 用双类名.tw-hidden获得更高优先级见下方插件自定义插件中定义了.hidden.hidden { display: none }即tw-hidden.tw-hidden并逐条注释了为什么不能用[hidden]属性打不过display: flex、不能用原生.hidden被 Fomantic 污染、不能用内联styledisplay:none难以微调、也不能用 jQuery 的 show/hide/toggle对display: xxx !important无效content扫描范围不仅包含模板与前端源码还包含build/models/modules/routers/services下的.go文件——因为 Go 代码中包括测试文件也会出现class...字符串Tailwind 需要据此生成类颜色 token如tw-bg-primary来自 web_src/css/themes/theme-gitea-light.css 与theme-gitea-dark.css中:root定义的--color-*CSS 变量由构建时自动抽取tailwind.config.ts因此暗色主题切换无需重编译样式。模板中的 class 书写方式规范要求在模板中把 class 属性写成一个可整体阅读的单位例如div classflex-text-inline {{if .IsFoo}}tw-hidden{{end}}/div而不是把条件类拆分到多处拼接。六、TypeScript 风格规则guidelines-frontend.md 对 TypeScript 给出三条明确规则类型导入一律用import type已知必然存在的值用!非空断言而不是用?./??掩盖确定的事实例如 fetch-action.ts 中el.getAttribute(data-url)!的写法就是这一约定的体现函数只有真正await或返回Promise才标记async避免异步事件监听器无法避免时必须在第一个await之前调用e.preventDefault()——否则默认行为如表单提交、链接跳转会在异步回调执行前抢先发生。七、数据获取fetch.ts 封装与 fetch-action 框架7.1 底层封装web_src/js/modules/fetch.ts规范明确要求不要直接使用裸fetch而是使用web_src/js/modules/fetch.ts导出的GET、POST、PUT、PATCH、DELETE包装函数。该文件只有 33 行核心逻辑是export function request(url: string, {method GET, data, headers {}, ...other}: RequestOpts {}): PromiseResponse { let body: string | FormData | URLSearchParams | undefined; let contentType: string | undefined; if (data instanceof FormData || data instanceof URLSearchParams) { body data; } else if (isObject(data) || Array.isArray(data)) { contentType application/json; body JSON.stringify(data); } headers new Headers(headers); if (!headers.has(content-type) contentType) { headers.set(content-type, contentType); } return fetch(url, {method, headers, ...other, ...(body {body})}); } export const GET (url: string, opts?: RequestOpts) request(url, {method: GET, ...opts}); export const POST (url: string, opts?: RequestOpts) request(url, {method: POST, ...opts}); // PATCH / PUT / DELETE 同理它的价值在于把data选项统一转换为请求体——FormData/URLSearchParams原样透传浏览器自动设置正确的Content-Type普通对象/数组则自动JSON.stringify并设置application/json头调用方无需关心序列化细节。文件顶部注释也说明这是 eslint 规则中唯一被豁免使用裸fetch的位置。7.2 声明式请求框架web_src/js/modules/fetch-action.ts对于表单提交、按钮点击和一般网络请求规范推荐优先使用 web_src/js/modules/fetch-action.ts 框架理由是它提供一致的 UX 与错误处理。从源码看initGlobalFetchAction这是一套“类 HTMX”的声明式系统元素上的属性即行为配置属性含义data-fetch-url请求目标 URLdata-fetch-methodHTTP 方法。fetch 触发默认GETlink-action元素默认POST表单则忽略该属性以表单method为准缺省GETdata-fetch-trigger触发时机click、change用户触发、load页面加载、every 5s定时也支持ms单位、fetch-reload仅在 fetch-sync 成功后由内部触发用于刷新过时内容data-fetch-indicator加载指示元素选择器语法与data-fetch-sync相同用户触发默认$this元素自身按钮会直接disabled其他元素加is-loading类data-fetch-sync响应为 HTML 时的页面更新伪选择器命令见下data-modal-confirm动作前弹出确认框可以是提示文本也可以是#modal-id引用已有模态框并支持-header、-content变体两个开箱即用的语义化 class.link-actiona classlink-action>export function toggleElem(el: ElementArg, force?: boolean): ArrayLikeIterableElement { return toggleElemClass(el, tw-hidden, force undefined ? force : !force); } export function showElem(el: ElementArg) { return toggleElem(el, true); } export function hideElem(el: ElementArg) { return toggleElem(el, false); }这与 tailwind.config.ts 的注释是配套的.tw-hidden双类名提权必须能压过一切display: xxx !important是 Gitea 中唯一被认可的隐藏手段。九、UI 组件画廊/devtest 页面开发模式下Gitea 提供标准化的UI 组件画廊访问/devtest如http://localhost:3000/devtest集中预览各类组件的当前渲染效果这些页面同时被 e2e 测试复用tests/e2e/。从源码看该路由组定义在 routers/web/web.gom.Group(/devtest, ...)处理器位于 routers/web/devtest/ 包devtest.go 的List会遍历 templates/devtest/ 目录列出所有组件模板页如form-fields、fomantic-dropdown、toast-and-message、relative-time等TmplCommon按{sub}参数渲染对应模板此外还提供fetch-action-test、mail-preview以及 Actions 运行视图的 mock 数据mock_actions.go等专门测试端点。这构成了一条“改样式/组件 → 在/devtest目检 → e2e 自动回归”的闭环是验证前端改动的第一现场。十、小结Gitea 的前端规范本质上是一套“在框架混排中维持秩序”的工程约定架构上Go 模板保底简单/SEO 页面Vue 3无 JSX承接复杂交互Fomantic-UI 存量维护并逐步退出命名上tw-/gt-/g-/ce-等前缀体系与 kebab-case 约束杜绝了跨框架命名污染数据流上fetch.ts统一请求序列化fetch-action以声明式属性接管“确认 → 加载指示 → 请求 → 错误 toast/字段标红 → 局部更新/跳转”的完整链路工程上pnpm 锁定已发布版本Tailwind 扫描 Go 源码与模板/devtest组件画廊与 e2e 测试共同保障 UI 回归。遵循 docs/guidelines-frontend.md 的上述约定再配合 docs/CONTRIBUTING.md 对应的工作流、docs/development.md 的构建方式与 docs/testing.md 的测试要求即可在 Gitea 前端中安全、规范地开展开发。【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考