mss-boot-admin

English | 简体中文

Introduction

mss-boot-admin is a front-end and back-end separation admin platform based on Gin, React, Ant Design v5, Umi v4, and mss-boot. Its current product focus is governance, operations, configuration, access control, internationalization, and AI-annotation-assisted engineering collaboration.

The repository still contains some historical dynamic-model and code-generation related capabilities, but they are no longer the primary direction for future product investment.

Recent Updates

The project has undergone comprehensive polish rounds focusing on:

• Stability (P0): Fixed nil dereference risks, boundary checks, panic prevention, auth coverage, and polling cleanup
• Code Quality: Eliminated all TypeScript errors, unified page structures, removed duplicate keys
• Abstraction: Created reusable components (AuthShell, useMonitorData hook), unified API response format
• Testing: Documented 70+ test cases, executed core scenarios successfully
• Documentation: Added CHANGELOG, CONTRIBUTING guide, and comprehensive configuration tutorial

Beta Environment

Swagger

Tutorial

Online documentation Video tutorial

Project address

Backend project Front-end project

🎬 Experience environment

Experience address

Account: admin Password: 123456

✨ Features

• Support internationalization
• Standard Restful API development specifications
• RBAC permission management based on Casbin
• Database storage based on Gorm
• Middleware development based on Gin
• Swagger document generation based on Gin
• Support oauth2.0 third-party login
• Support swagger document generation
• Support multiple configuration sources (local files, embed, object storage s3, etc., databases supported by gorm, mongodb)
• Support database migration
• Support governance-oriented admin modules such as users, roles, menus, departments, posts, APIs, and configuration
• Support operational modules such as notices, tasks, monitoring, and statistics
• Evolving toward AI-annotation-assisted engineering workflows for clearer collaboration and delivery discipline

📦 Built-in functions

• User management: Users are system operators, and this function mainly completes the configuration of system users.
• Department management: Maintain organization hierarchy and ownership boundaries.
• Post management: Maintain post data for organization and permission collaboration.
• Role management: Role menu permission allocation, set role data range permission division by organization.
• Menu management: Configure system menus, operation permissions, button permission identifiers, etc.
• API management: Maintain API registry information for governance and permission mapping.
• Option management: dynamically configure enumerations.
• System configuration: Manage the configuration of various environments.
• Notice announcement: user notification message.
• Task management: Manage scheduled tasks, including execution logs.
• Internationalization management: Manage internationalization resources.
• Account and token management: Support OAuth2 binding and personal access tokens.
• Monitoring and statistics: Provide runtime visibility and statistics querying capabilities.

RBAC Glossary

Term	Meaning in mss-boot-admin
User	A system operator. Users authenticate, receive roles, and operate within the permissions granted by those roles.
Role	A permission group stored in mss_boot_roles. Roles are the main subject in Casbin policies and are assigned to users.
Menu	A frontend navigation or permission node stored in mss_boot_menus. Menu records can represent directories, pages, components, or API permission nodes.
API	A backend route record stored in mss_boot_api, usually generated from Gin route metadata and used for permission governance.
Permission path	The menu/API path written into authorization requests and Casbin rules. Duplicate or blank paths are ignored before rules are built.
Casbin rule	A policy row in mss_boot_casbin_rule. The common shape is p, roleID, accessType, path, method.
Access type	The rule scope, such as MENU, API, or component access. Role authorization can combine menu rules and child API rules.
Data scope	The organization/data boundary attached to a role. It controls which department-owned data a role should be able to access.
Default role	A role marked as default. New menu access can be granted to it automatically when menu records are created.

📦 Preparation

• Install Go 1.26+
• Optional for backend integration testing: MySQL 8.0+ and Redis 7+
• Frontend development: Node.js 22+ and pnpm 9+

📦 Quick start

1. Download the project

# Download the backend project
git clone https://github.com/mss-boot-io/mss-boot-admin.git
# Download the front-end project
git clone https://github.com/mss-boot-io/mss-boot-admin-antd.git

2. Migrate the database

# Enter the backend project
cd mss-boot-admin
# The default local config uses SQLite: mss-boot-admin-local.db
go run main.go migrate

If you want to use MySQL locally, start compose/mysql/docker-compose.yml and update config/application.yml (database.driver and database.source) before running the migration command.

3. Generate API interface information

# Generate API interface information
go run main.go server -a

4. Start the backend service

# Start the backend service
go run main.go server

5. Start the front-end service

# Enter the front-end project
cd mss-boot-admin-antd
# Install dependencies
corepack enable
pnpm install
# Start the front-end service
pnpm start:dev

📨 Interaction

				mss-boot-io
telegram🔥🔥🔥	WeChat	WeChat MP🔥🔥🔥		bilibili🔥🔥🔥

💎 Contributors

JetBrains open source certificate support

The mss-boot-io project has always been developed in the GoLand integrated development environment under JetBrains, based on the free JetBrains Open Source license(s) genuine free license. I would like to express my gratitude.

🤝 Special thanks

1. ant-design
2. ant-design-pro
3. umi
4. gin
5. casbin
6. gorm
7. gin-swagger
8. jwt-go
9. oauth2

🤟 Sponsor Us

If you think this project helped you, you can buy a glass of juice for the author to show encouragement 🍹

Testing

The project follows strict testing requirements to ensure code quality and reliability.

Local Test Prerequisites

make test runs go test -coverprofile=coverage.out ./.... Before opening a backend PR, check these local prerequisites:

• Use Go 1.26+, matching go.mod and GitHub Actions.
• Run make deps once after pulling dependency or go.sum changes.
• Redis-backed tests generally use miniredis, but a local Redis 7 instance is useful when validating cache/session behavior manually.
• No real production DSN, token, Kubernetes cluster, or private credential is required for make test.
• CI starts Redis 7 with supercharge/redis-github-action, then runs make deps, make test, and make build.

If a local test fails because an optional external service is unavailable, mention that in the PR verification notes and include the exact command output. Do not paste real credentials or production endpoints.

Test Types

1. Unit Tests

• Location: *_test.go alongside source files
• Minimum coverage: 80%
• Run command:

  go test ./... -v -coverprofile=coverage.out

• Verify coverage:

  go tool cover -html=coverage.out
  # Or check terminal summary
  go tool cover -func=coverage.out | grep total

2. Integration Tests

• Focus: API endpoints with database interactions
• Test databases: Use test databases (SQLite in-memory for unit tests, real DB for integration)
• Run command:

  go test -tags=integration ./...

• Verify: Database migrations, API contracts, and service integrations

3. End-to-End (E2E) Tests

• Full Stack Testing: Uses Playwright for browser automation
• Critical user flows: login, CRUD operations, permissions
• Run command: pnpm e2e (executed in frontend project)

Development Workflow

1. DEVELOPMENT PHASE
   └── Write code
   └── Write tests (TDD preferred)
   └── Ensure compilation

2. TESTING PHASE (MANDATORY)
   ├── Unit Tests: go test ./...
   ├── Integration Tests: go test -tags=integration ./...
   └── E2E Tests: pnpm e2e (for major features)

3. VERIFICATION PHASE
   ├── Check test coverage (≥80%)
   ├── All tests must pass
   └── Document test results

Coverage Requirements by Component

Component	Unit Tests	Integration Tests	Min Coverage
Models	✅ Required	Optional	80%
Services	✅ Required	✅ Required	85%
APIs	✅ Required	✅ Required	80%
Utils	✅ Required	Optional	90%

Test Structure Example

// service/user_test.go
package service

import (
    "testing"
    "github.com/stretchr/testify/assert"
)

func TestUserService_Create(t *testing.T) {
    // Setup
    db := setupTestDB(t)
    svc := &UserService{}
    
    // Execute
    user, err := svc.Create(ctx, &CreateUserRequest{...})
    
    // Verify
    assert.NoError(t, err)
    assert.NotNil(t, user)
    assert.Equal(t, "expected", user.Field)
}

Pre-commit Hooks

Before committing, run:

# Run all tests
go test ./... -v -race -coverprofile=coverage.out

# Check coverage meets requirements
go tool cover -func=coverage.out | grep total # Must be ≥ 80.0%

🔑 License

MIT

Copyright (c) 2024 mss-boot-io