03. 核心概念在开始代码开发之前，我们需要了解一些核心概念。这些概念对于理解项目架构至关重要。什么是 Gitea？

03. 核心概念

在开始代码开发之前，我们需要了解一些核心概念。这些概念对于理解项目架构至关重要。

什么是 Gitea？

Gitea 是一个开源的轻量级 Git 服务，由 Go 语言编写。它提供了 Web 界面来托管和管理 Git 仓库。

Gitea API

Gitea 提供了完整的 RESTful API，允许程序化访问仓库数据。本项目主要使用以下 API：

API 端点	说明
`GET /user`	获取当前用户信息
`GET /user/repos`	获取用户仓库列表
`GET /repos/{owner}/{repo}/commits`	获取仓库提交历史
`GET /repos/{owner}/{repo}/branches`	获取仓库分支
`GET /repos/{owner}/{repo}/contributors`	获取贡献者统计

认证方式

使用 个人访问令牌（Personal Access Token） 进行认证：

# 在请求头中传递令牌
Authorization: token YOUR_ACCESS_TOKEN

RESTful API 设计

本项目的后端遵循 RESTful 设计原则。

资源命名

使用名词而非动词：/repos 而非 /getRepos
使用复数形式：/commits 而非 /commit
使用层级关系：/repos/{owner}/{repo}/commits

HTTP 方法

方法	用途	示例
GET	获取资源	`GET /repos` 获取仓库列表
POST	创建资源	`POST /sync/repos` 同步仓库
PUT	更新资源	更新配置
DELETE	删除资源	删除记录

响应格式

所有 API 响应采用统一的 JSON 格式：

{
  "success": true,
  "message": "操作成功",
  "data": {
    // 实际数据
  },
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100
  }
}

数据库基础

PostgreSQL

PostgreSQL 是一个功能强大的开源关系型数据库。本项目使用 PostgreSQL 存储：

仓库信息
提交记录
贡献者数据
用户配置
AI 会话历史

Bun ORM

Bun ORM 是 Bun 生态中的数据库 ORM，可用于 Go 项目。它提供：

类型安全的数据库操作
简洁的查询 API
自动迁移

// 示例：查询仓库
var repos []Repo
db.Find(&repos)

前端架构概念

组件化开发

React 的核心思想是将 UI 拆分为独立的组件：

// 一个简单的 React 组件
function RepoCard({ name, stars, language }) {
  return (
    <div className="card">
      <h3>{name}</h3>
      <p>⭐ {stars} · {language}</p>
    </div>
  );
}

状态管理

项目使用 Zustand 进行状态管理：

import { create } from 'zustand';

const useStore = create((set) => ({
  repos: [],
  setRepos: (repos) => set({ repos }),
}));

服务端状态

React Query 管理服务端状态（API 数据）：

import { useQuery } from '@tanstack/react-query';

function RepoList() {
  const { data, isLoading } = useQuery({
    queryKey: ['repos'],
    queryFn: () => fetchRepos()
  });

  if (isLoading) return <Loading />;
  return <List data={data} />;
}

AI Agent 概念

什么是 Agent？

AI Agent（智能代理）是一种能够自主执行任务的 AI 系统。它可以：

理解用户意图
调用工具完成操作
保持对话上下文

工具注册

Agent 通过注册工具来扩展能力：

// 示例：注册获取仓库的工具
agent.RegisterTool("get_repos", func(params map[string]interface{}) {
    // 获取仓库列表
})

对话流程

flowchart LR
    User[用户输入] --> Agent[AI Agent]
    Agent --> Tool1{调用工具?}
    Tool1 -->|是| API[调用 API]
    API --> Tool1
    Tool1 -->|否| LLM[调用 LLM]
    LLM --> Agent
    Agent --> User

接下来

核心概念已掌握！下一节我们将开始学习 Go 语言基础。