# 使用 GitHub 登录：OAuth 2.0 接入指南（Golang）

本文介绍在自有应用中接入 **GitHub 账号** 的通用做法：在 GitHub 注册 OAuth App，使用 **授权码流程** 换取 `access_token`，并调用 GitHub REST API 获取用户信息。与具体业务系统无关。

## 1. 协议与端点

GitHub 支持标准 OAuth 2.0。Go 中可直接使用：

```text
import "golang.org/x/oauth2/github"

Endpoint: github.Endpoint  // AuthURL + TokenURL 已内置
```

| 步骤 | URL |
|------|-----|
| 引导用户授权 | `https://github.com/login/oauth/authorize`（由 `oauth2.Config` 生成） |
| 用 `code` 换 token | `https://github.com/login/oauth/access_token`（`Exchange` 自动 POST） |
| 读当前用户（示例） | `GET https://api.github.com/user`（`Authorization: Bearer {token}`） |
| 主邮箱（若 user 里无 email） | `GET https://api.github.com/user/emails` |

常用 **Scope**：`read:user`、`user:email`（需要邮箱时建议带 `user:email`）。

官方文档：[Authorizing OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)

## 2. 在 GitHub 注册应用

1. 个人：`Settings` → `Developer settings` → `OAuth Apps` → `New OAuth App`。  
2. **Authorization callback URL** 填你**真实**的回调地址，例如：  
   `http://localhost:8080/oauth/github/callback`（开发）  
   `https://你的域名/oauth/github/callback`（生产）  
3. 保存 **Client ID** 与 **Client secrets**（机密只显示一次，可轮换）。

## 3. `redirect_uri` 与换 token

- 授权请求中的 `redirect_uri` 与在 GitHub 登记的 **必须完全一致**。  
- 用 `code` 换 token 时，客户端库会带上**同一** `redirect_uri`，否则换 token 失败。

## 4. Golang 最小示例（授权码 + 拉取用户）

依赖：`go get golang.org/x/oauth2`，并安装子包引用 `github.Endpoint`（同一 module）。

```go
package main

import (
	"context"
	"crypto/rand"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"sync"
	"time"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/github"
)

func main() {
	redirectURL := getenv("OAUTH_REDIRECT_URL", "http://127.0.0.1:8080/oauth/github/callback")
	cfg := &oauth2.Config{
		ClientID:     os.Getenv("GITHUB_CLIENT_ID"),
		ClientSecret: os.Getenv("GITHUB_CLIENT_SECRET"),
		RedirectURL:  redirectURL,
		Scopes:       []string{"read:user", "user:email"},
		Endpoint:     github.Endpoint,
	}
	if cfg.ClientID == "" || cfg.ClientSecret == "" {
		log.Fatal("set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET")
	}

	states := newStateStore()

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		b := make([]byte, 16)
		_, _ = rand.Read(b)
		state := base64.RawURLEncoding.EncodeToString(b)
		states.Put(state, time.Now().Add(10*time.Minute))
		url := cfg.AuthCodeURL(state, oauth2.AccessTypeOnline)
		http.Redirect(w, r, url, http.StatusFound)
	})

	http.HandleFunc("/oauth/github/callback", func(w http.ResponseWriter, r *http.Request) {
		if err := r.URL.Query().Get("error"); err != "" {
			http.Error(w, r.URL.Query().Get("error_description"), http.StatusBadRequest)
			return
		}
		state := r.URL.Query().Get("state")
		code := r.URL.Query().Get("code")
		if !states.Consume(state) {
			http.Error(w, "invalid state", http.StatusBadRequest)
			return
		}
		ctx := r.Context()
		tok, err := cfg.Exchange(ctx, code)
		if err != nil {
			http.Error(w, "token exchange: "+err.Error(), http.StatusBadRequest)
			return
		}
		u, err := fetchGitHubUser(ctx, tok.AccessToken)
		if err != nil {
			http.Error(w, err.Error(), http.StatusBadGateway)
			return
		}
		w.Header().Set("Content-Type", "application/json; charset=utf-8")
		_ = json.NewEncoder(w).Encode(u)
	})

	log.Println("open http://127.0.0.1:8080/  (callback must match GitHub app:", redirectURL+")")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

type ghUser struct {
	ID        int64  `json:"id"`
	Login     string `json:"login"`
	Name      string `json:"name"`
	AvatarURL string `json:"avatar_url"`
}

func fetchGitHubUser(ctx context.Context, access string) (*ghUser, error) {
	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/user", nil)
	req.Header.Set("Authorization", "Bearer "+access)
	req.Header.Set("Accept", "application/vnd.github+json")
	req.Header.Set("User-Agent", "oauth-demo")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	if res.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("github user: %d %s", res.StatusCode, b)
	}
	var u ghUser
	if err := json.Unmarshal(b, &u); err != nil {
		return nil, err
	}
	return &u, nil
}

type stateStore struct {
	mu  sync.Mutex
	m   map[string]time.Time
}

func newStateStore() *stateStore {
	return &stateStore{m: make(map[string]time.Time)}
}

func (s *stateStore) Put(key string, exp time.Time) {
	s.mu.Lock()
	s.m[key] = exp
	s.mu.Unlock()
}

func (s *stateStore) Consume(key string) bool {
	s.mu.Lock()
	defer s.mu.Unlock()
	t, ok := s.m[key]
	if !ok || time.Now().After(t) {
		return false
	}
	delete(s.m, key)
	return true
}

func getenv(k, def string) string {
	if v := os.Getenv(k); v != "" {
		return v
	}
	return def
}
```

**运行前**：

- 在 GitHub OAuth App 的回调里填写与 `OAUTH_REDIRECT_URL` **完全一致**的 URL（未设置时默认 `http://127.0.0.1:8080/oauth/github/callback`）。  
- `export GITHUB_CLIENT_ID=...` 与 `GITHUB_CLIENT_SECRET=...`

## 5. 常见错误

| 现象 | 原因 |
|------|------|
| `redirect_uri` 与登记不符 | 修改了端口、`localhost` vs `127.0.0.1` 或 `http`/`https` 不一致 |
| 换 token 失败 | 同上；或 `Client Secret` 错误 |
| 用户 email 为空 | 邮箱可能未公开，需调 `user/emails` 并带 `user:email` scope |

## 6. 安全建议

- `state` 应随机且**一次性**；生产可用加签或服务端 Session。  
- `Client Secret` 仅放服务端；勿写入前端。  
- 对 GitHub 用户 ID（数字 id）做账号绑定主键，勿仅用 login（可改名）。