quickstart.md 10.0 KB

原文件审查历史永久链接



SMF Core 快速入门指南

本文档旨在帮助开发者快速了解和开始使用SMF Core框架，通过简明的步骤指导您完成从环境准备到功能实现的全过程。


1. 环境准备


1.1 必备软件


JDK 1.8或更高版本
Maven 3.6或更高版本
MongoDB 4.0或更高版本
IDE（推荐IntelliJ IDEA或Eclipse）


1.2 验证环境

# 检查Java版本
java -version

# 检查Maven版本
mvn -version

# 检查MongoDB服务状态
# 对于Linux/Mac
mongo --eval 'db.runCommand({ connectionStatus: 1 })'

# 对于Windows
mongo --eval "db.runCommand({ connectionStatus: 1 })"


2. 项目设置


2.1 创建新项目

您可以通过以下方式开始一个新的SMF Core项目：


2.1.1 使用现有项目模板（推荐）

# 克隆示例项目（假设）
git clone https://example.com/smf-core-starter.git my-smf-project
cd my-smf-project


2.1.2 手动创建Maven项目

创建一个新的Maven项目，并在pom.xml中添加SMF Core依赖：

<dependencies>
    <!-- SMF Core 依赖 -->
    <dependency>
        <groupId>com.neotel.smfcore</groupId>
        <artifactId>smf-core</artifactId>
        <version>1.0.0</version> <!-- 使用实际版本号 -->
    </dependency>

    <!-- Spring Boot 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!-- 其他必需依赖 -->
</dependencies>


2.2 项目结构

创建以下基本目录结构：

my-smf-project/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── mysmfproject/
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               ├── dao/
│   │   │               ├── entity/
│   │   │               ├── dto/
│   │   │               ├── mapper/
│   │   │               └── MySmfProjectApplication.java
│   │   └── resources/
│   │       ├── smfcore.json
│   │       ├── log4j2-spring.xml
│   │       └── messages_zh_CN.properties
│   └── test/
│       └── java/
└── pom.xml


3. 配置框架


3.1 核心配置文件

在src/main/resources/目录下创建smfcore.json配置文件：

{
  "database": {
    "mongo": {
      "uri": "mongodb://localhost:27017/my-smf-project"
    }
  },
  "service": {
    "port": 8080,
    "contextPath": "/my-smf"
  },
  "i18n": {
    "defaultLocale": "zh_CN",
    "supportedLocales": ["zh_CN"]
  }
}


3.2 创建国际化资源文件

在src/main/resources/目录下创建messages_zh_CN.properties：

app.name=我的SMF项目
welcome.message=欢迎使用SMF Core框架
user.create.success=用户创建成功
user.not.found=用户不存在


4. 实现基本功能


4.1 创建实体类

package com.example.mysmfproject.entity;

import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;

@Document(collection = "users")
public class UserEntity {

    @Id
    private String id;
    private String username;
    private String email;
    private String fullName;
    private boolean active;

    // 构造函数、Getter和Setter方法

    public UserEntity() {
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }

    public boolean isActive() {
        return active;
    }

    public void setActive(boolean active) {
        this.active = active;
    }
}


4.2 创建DTO类

package com.example.mysmfproject.dto;

public class UserDto {

    private String id;
    private String username;
    private String email;
    private String fullName;
    private boolean active;

    // 构造函数、Getter和Setter方法

    public UserDto() {
    }

    // Getter和Setter方法（与UserEntity类似）
    // ...
}


4.3 创建DAO接口和实现

package com.example.mysmfproject.dao;

import com.example.mysmfproject.entity.UserEntity;
import com.neotel.smfcore.common.base.AbstractBaseDao;
import org.springframework.stereotype.Repository;

@Repository
public class UserDao extends AbstractBaseDao<UserEntity> {

    // 可以添加自定义查询方法

    public UserEntity findByUsername(String username) {
        return findOneByField("username", username);
    }
}


4.4 创建Mapper接口和实现

package com.example.mysmfproject.mapper;

import com.example.mysmfproject.dto.UserDto;
import com.example.mysmfproject.entity.UserEntity;
import com.neotel.smfcore.common.base.BaseMapper;
import org.springframework.stereotype.Component;

public interface UserMapper extends BaseMapper<UserDto, UserEntity> {
}

@Component
class UserMapperImpl implements UserMapper {

    @Override
    public UserEntity toEntity(UserDto dto) {
        if (dto == null) {
            return null;
        }

        UserEntity entity = new UserEntity();
        entity.setId(dto.getId());
        entity.setUsername(dto.getUsername());
        entity.setEmail(dto.getEmail());
        entity.setFullName(dto.getFullName());
        entity.setActive(dto.isActive());

        return entity;
    }

    @Override
    public UserDto toDto(UserEntity entity) {
        if (entity == null) {
            return null;
        }

        UserDto dto = new UserDto();
        dto.setId(entity.getId());
        dto.setUsername(entity.getUsername());
        dto.setEmail(entity.getEmail());
        dto.setFullName(entity.getFullName());
        dto.setActive(entity.isActive());

        return dto;
    }

    // 实现其他必需的方法
}


4.5 创建Service类

package com.example.mysmfproject.service;

import com.example.mysmfproject.dao.UserDao;
import com.example.mysmfproject.dto.UserDto;
import com.example.mysmfproject.mapper.UserMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Autowired
    private UserDao userDao;

    @Autowired
    private UserMapper userMapper;

    public UserDto createUser(UserDto userDto) {
        // 验证和业务逻辑
        // ...

        // DTO转Entity
        UserEntity entity = userMapper.toEntity(userDto);

        // 保存到数据库
        entity = userDao.save(entity);

        // Entity转回DTO并返回
        return userMapper.toDto(entity);
    }

    public UserDto getUserById(String id) {
        UserEntity entity = userDao.findById(id);
        return userMapper.toDto(entity);
    }
}


4.6 创建Controller类

package com.example.mysmfproject.controller;

import com.example.mysmfproject.dto.UserDto;
import com.example.mysmfproject.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    @PostMapping
    public UserDto createUser(@RequestBody UserDto userDto) {
        return userService.createUser(userDto);
    }

    @GetMapping("/{id}")
    public UserDto getUserById(@PathVariable String id) {
        return userService.getUserById(id);
    }
}


4.7 创建应用程序入口

package com.example.mysmfproject;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.neotel.smfcore.common.base.annotation.EnableSmfCore;

@SpringBootApplication
@EnableSmfCore // 启用SMF Core功能
public class MySmfProjectApplication {

    public static void main(String[] args) {
        SpringApplication.run(MySmfProjectApplication.class, args);
    }
}


5. 测试应用程序


5.1 运行应用程序

# 编译并运行应用
./mvnw spring-boot:run


5.2 测试API接口

使用curl命令或Postman等工具测试API：

# 创建用户
curl -X POST http://localhost:8080/my-smf/api/users \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com","fullName":"测试用户","active":true}'

# 查询用户
curl http://localhost:8080/my-smf/api/users/{id}


6. 常用功能快速实现


6.1 使用国际化消息

@Service
public class MessageService {

    @Autowired
    private MessageSource messageSource;

    public String getMessage(String code, Object[] args) {
        return messageSource.getMessage(code, args, LocaleContextHolder.getLocale());
    }
}


6.2 添加日志记录

@Service
public class LoggingService {

    private static final Logger logger = LoggerFactory.getLogger(LoggingService.class);

    public void logInfo(String message) {
        logger.info(message);
    }

    public void logError(String message, Throwable throwable) {
        logger.error(message, throwable);
    }
}


7. 后续步骤


查阅  了解更多API详情
阅读  掌握框架架构
查看  了解更多配置选项


最后更新时间：2024年