[Java Experience Sharing 01] How does Xiaobai start to learn to look at open source projects?

foreword

This article is purely personal for aHow does a novice with a certain foundationI started to look at my first open source project to do some analysis. Therefore, I chose a project whose technical architecture is not difficult, and it is more friendly to novices. It is purely for sharing and I hope it will be useful to friends who already have a certain code foundation!

1. Understand open source

1.1. What is open source?

​ Generally speaking, if the referenceopen source, the first thing people think of is that theThe code is made public, such as GitHubon The following is a detailed talk about the connotation and extension of the concept of open source, so as to quickly understand the concept and extension of open source. For the most authoritative explanation of open source, please refer to https://opensource.org . This website is where the idea of ​​​​open source was born. In China, there are also open source websites such as Open Source China.

​ Recommended by open source communities at home and abroad: Open Source China , ChinaUnix , GitHub , Apache , SourceForge ,

1.2. Definition of open source

​ Let’s first give a definition of open source, a piece of software is open source,The most basic meaning is that the code is public, and anyone can view, modify and use it.

First, open source code is very different from closed source code. Closed source code is ordinary commercial copyright software, the code is closed, only the author can see it, and only he can modify it if there is a problem. And open source code,Anyone can view and edit. There is a very interesting story about the birth of open source thinking. Richard StallmanHe is one of the greatest hackers of all time and one of the most coders in the world. He once bought a piece of commercial software, and there was a little problem, so he went to the software company and asked if they could help fix it. After a while, the software company said no, so Richard said, can you give me the code, and I will fix it, but the company also said no. So Richard Stallman was very angry and founded the Free Software Foundation,The famous GPL agreement was released, and the GPL is still the most famous open source agreement so far.

The second point that requires special attention is that,Open source does not mean free. Although software codes can be given to others for free, software-related services, such as compilation, maintenance and upgrades, can also make money. For example, Redhat is an open source software company that not only makes money, but also makes money. At the same time, many companies are investing more and more developers in the company's open source projects. These software can strongly support the company's ecology, so if you are an open source software developer, you don't have to worry about finding a job.

1.2.1. Advantages of open source software

advantage	illustrate
low risk	Using closed source software is undoubtedly handing over your fate to others. Once the closed source code is not maintained by anyone, you will be in a dilemma. Compared with commercial software companies, open source communities rarely have the problem of going bankrupt.
high quality	Compared with closed-source software products, open-source projects are usually developed and maintained by the open-source community. There are many users involved in writing, maintaining, and testing. Generally, bugs are fixed before they break out.
low cost	Open source workers are silently and unpaid behind the scenes to contribute to a better world. Therefore, using software projects promoted by the open source community can save a lot of manpower, material and financial resources.
more transparent	No idiot will put Trojan horses, backdoors, etc. into open source code, which will undoubtedly expose his crimes to the sun.

1.2.2. Classic open source software case

software	illustrate
Linux	Linux is an open source operating system, and its kernel is jointly maintained by many geeks. Linux is the classic, representative, and pinnacle of open source software.
Apache	The #1 Web server software used in the world.
MySQL	The world's most popular relational database, suitable for small and medium-sized websites.
Firefox	Firefox browser. Before Chrome came out, Firefox was pretty much the fastest browser, and until now is the debugging tool for web developers.
OpenOffice	A cross-platform office software suite, similar to Microsoft Office.
GCC	C language/C++ compiler.
Java、PHP、 Python	Open source programming language.

1.3. About the open source agreement

While pursuing "freedom", open source software cannot sacrifice the interests of programmers, otherwise it will affect the creative passion of programmers. Therefore, there are now more than 60 open source license agreements recognized by the Open Source Initiative in the world. Guarantee the rights and interests of open source workers.

The open source agreement stipulates your rights and responsibilities when using open source software, that is, what you can and cannot do.

1.3.1. How to choose an open source protocol

There are hundreds of open source protocols in the world, and few people can fully understand the differences between them, even among the six most popular open source protocols - GPL, BSD, MIT, Mozilla, Apache, and LGPL - Choices are also complicated.

Ukrainian programmer Paul Bagwell drew an analysis diagram to illustrate how to choose an open source protocol. Everyone can see it at a glance, which is really refreshing.

2. How to find open source projects

​ First of all, there are two websites to introduce when looking for open source projects. One is GitHub , which is well known as the world's largest same-sex dating platform, and the second is Code Cloud, a popular code management platform in China in recent years . If you want to find better open source projects, you can usually search on these two platforms. Of course, searching also requires skills.

Common keyword analysis of code management platform

• watch: Will continue to receive project updates
• fork: Copy an item to your own warehouse
• star: The number of likes indicates that the project is recognized, and the more likes the more popular the project is
• clone: Download the project to the local
• follow: Follow the authors you are interested in, and you will receive their updates

2.1. Basic analysis of a warehouse project

Analysis of some key information

• Issues（问题单）: Used to track, enhance, and troubleshoot projects. They are just like emails - except they can be shared and discussed with the rest of the team
• The hotter the project startand forkthe more
• commit: Generally better projects, maintenance will be more frequent, updates will be frequent, and the number of submissions will be more
• README.mdThe file is an introductory manual for a project, which introduces the use, functions, etc. of the entire project. So whether the README file is well written is related to whether this project can be understood and used by others more easily.
• You can also check whether you have downloaded the ancient project according to the last update time of the project

2.2. About Advanced Search for Open Source Projects

GitHub hasadvanced search function, search/advanced can input 关键字, 代码库大小, contains 作者, 代码语, 代码包含后缀文件名etc.

Note: Search formulas can be used in combination. Separate each formula with a space!

2.3. Search according to warehouse title and description

in keyword to limit the search scope

• in:name xxxProject name contains xxx
• in:description xxxItem description contains xxx
• in:readme xxxThe project introduction document contains xxx

in:限制 搜索的具体内容Do a more precise search for

2.4. Search by region and language

​ Many times our project is to uselanguage we know, you found a Pythonwell-written project, but you haven’t studied it Python, and you can’t understand it even after downloading it. At the same time, 为了更好的阅读README.md帮助文档以及项目注释, I think many students will want to download itChinese project, Of course, please ignore the top-notch English. At this time, you can search by region and language.

• location: area
• language: language

#语言为javaScript   
language:javaScript   
#地区为china
location: China
#可以进行联合搜索 如下：
language:javascript location:china

2.5. Search according to warehouse attribute conditions

According to personal needs, the project you may want to find is not that big, just some small projectsitem sizeLimit.

• size:>= 数字 Note: 100 represents 100Kb and the unit is Kb

If you want to find some relatively new items, you canAccording to the update time of the projectto search

• pushed:> YYYY-MM-DD Last upload date greater than YYYY-MM-DD
• created:> YYYY-MM-DD Creation date greater than YYYY-MM-DD

#比如我们想要寻找2020年最新更新的项目,可以如下
pushed:>2020-01-03 Spring Boot

#这样子就可以找到2020年1月之后更新的最新项目

2.6. Search by individual or organization

If you want to find out whether a certain master has submitted a new project on GitHub, you can perform an accurate search on them

• user: name find a user
• org: name find an organization
• followers:>=xxx Find developers with more than xxx followers

2.7. Search according to the LICENSE of the warehouse

​ of open source projectsLicense (Project Authorization Agreement)Some open source project authors explicitly prohibit commercial use, but if you download it without knowing it and use it, it will be very troublesome, so if you need to search for a project, you need to search for the project according to the corresponding open source agreement.

• license:对应协议

#例如咱们要找协议是最为宽松的 Apache License 2 的代码，如下
license:apache-2.0 Spring Boot

awesome enhanced search

Awesome seems to have become one of the favorite names of many GitHub projects. Awesome often integrates a large amount of information in the same field, so that everyone can learn better

• awesome 关键字The awesome series is generally used to collect items related to learning, tools, and books

For example, to search for excellent Javarelated projects, including frameworks and tutorials, you can enter:awesome Java

2.8. Popular

​ The GitHub Trend page summarizes what's trending on a daily/weekly/monthly cycleRepositories and Developers, you can see the development projects and developers that are hot in a certain cycle.

GitHub Topic showcases the latest and most popular discussion topics, here you can not only see development projects, but also more discussion topics about non-development technologies

3. Analysis of open source projects

3.1. Find related open source projects

​ According to different user usage (Chinese Gitee , global GitHub ), you can first look for open source projects from domestic open source websites. The following open source project cases come from Gitee. In Gitee, you can use the open source software on the homepage to find the most valuable projects. to view and search. Or you can observe and select items to learn based on recommended items

3.1.1. Open Source Projects

This open source project comes from an automated OA office system on Gitee . Thank you for the open source, if you like it, you can also give the boss a start . Office automation (OA) is the most frequently used application system for the daily operation and management of the organization, and it is used by employees and managers, which greatly improves the company's office efficiency.

3.2. How to analyze an open source project

3.2.1. Observe open source projects

​ First of all, for an open source project, the first thing to do should be to first observe the open source projectgeneral structure(such as instruction documents, sql files, project directory structure maven, etc. gradle), and basic information such as the language used.

3.2.2. Project technical analysis

View documentation - matching technology stack and operating environment

​ According to the usage documentation of the open source project, you can know which technology stacks the current project uses, and analyze whether they meet your needs based on these technology stacks. And check the operating environment requirements of the current project in order to proceed to the next step to run the project.

Taking the current open source case as an illustration, the technology stack is as follows:

front-end technology

technology	name	Version	official website
freemarker	template engine	springboot1.5.6.RELEASE integrated version	https://freemarker.apache.org/
Bootstrap	Front-end UI framework	3.3.7	http://www.bootcss.com/
Jquery	Fast JavaScript Framework	1.11.3	https://jquery.com/
kindeditor	HTML visual editor	4.1.10	http://kindeditor.net
My97 DatePicker	time picker	4.8 Beta4	http://www.my97.net/

backend technology

technology	name	Version	official website
SpringBoot	Spring Boot framework	1.5.6.RELEASE	https://spring.io/projects/spring-boot
JPA	spring-data-jpa	1.5.6.RELEASE	https://projects.spring.io/spring-data-jpa
My shoe	Mybatis framework	1.3.0	http://www.mybatis.org/mybatis-3
fastjson	json parsing package	1.2.36	https://github.com/alibaba/fastjson
pagehelper	Mybatis paging plugin	1.0.0	https://pagehelper.github.io

Deployment considerations

1. Download the project and import oasys.sql into the local database
2. Modify application.properties
3. Modify the data source, oasys --> your local library name, user name and password to your own
4. Modify the relevant path, configure the image path, file path, and attachment path. (copy static/image/oasys.jpg to the configured image path, otherwise FileNotFoundException will be reported)
5. The main method in OasysApplication.java runs, the console does not report an error message, and the operation is successful after the data startup time
6. Enter localhost:8088/login in the browser

3.2.3. Installation environment import project

​ Through the first round of observation, we can find and find the files needed to run the related project, then the next second step is to import this project into our IDE compilation tool, and try to run the project , to view it.

1. Import related sql files

​ Usually the author of an open source project will package the sql file of the project and put it into the open source project. You can generally see the relevant files in the homepage directory xxx.sql. If not, you can check if there is anyRelated folder called sql。

After finding the relevant database file,Create a new related database and run the SQL file.

2. Open the project with IDE tool

Prepare the relevant IDE tools. Usually, the projects placed on the code hosting platform will not be based on the specified compiler, but the core files of Maven will be retained.

Usually, open the IDE compilation tool and import the project on the corresponding path

3. Analyze directory structure

After the project is successfully imported, you can edit the project'sDirectory StructureDo a simple check to see if you can understand its general layout before starting the next in-depth project analysis

As can be seen from the above figure, even the directory structure of open source projects is based on the standard in the usual learning process, and it is alsoDivided by level, by function, by resource

3.2.4. About package-info.java

package-info.java​ In the process of viewing open source projects, you can see this class under many packages . package-info.javaIt is a Javafile that can be placed in any Javasource package for execution. However, the content inside has specific requirements, and its main purpose is toProvides package-level related operations, such as package-level annotations, annotations, and public variables.

1. Provide package-level annotations

Provide package-level annotations in the corresponding source code package. A simple example is as follows:

// 创建包注解
@Target(ElementType.PACKAGE)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestPkg {
    
    

}

//在package-info.java中添加注解
@TestPkg
package com.exercise.data_collection_error_info_transformation.component;

// 可以查看相关注解
public class Client {
    
    
    public static void main(String[] args) throws ClassNotFoundException {
    
    
    	// 查看包注解
        String pkgName = "com.exercise.data_collection_error_info_transformation.component";
        Package pkg = Package.getPackage(pkgName);
        Annotation[] annotations = pkg.getAnnotations();
        for(Annotation an:annotations){
    
    
            if(an instanceof TestPkg){
    
    
                System.out.println("Hi,I'm the TestPkg");

            }
        }

		// 查看包下面对应的类的注解
        Class test = Class.forName("com.exercise.data_collection_error_info_transformation.component.Test");
        Annotation[] annotations2 = test.getAnnotations();
        for(Annotation an:annotations2){
    
    
            if(an instanceof TestPkg){
    
    
                System.out.println("Hi,I'm the Class TestPkg");
            }
        }
    }
}
/**
得到最终结果如下：
	Hi,I'm the TestPkg
*/

If the entire package is outdated, you can directly package-info.javaadd a note below @Deprecatedto indicate that the source package is outdated

2. Provide package-level variables

If you want to use the corresponding variable in the package, but do not want other packages to use it, you can put the variable package-info.javabelow to realize 分包自用the idea.

/**
	在package-info.java类中添加如下内容
 * 包类
 */
class PACKAGE_CLASS{
    
    
    public void test(){
    
    
    }
}

/**
 * 包常量
 */
class PACKAGE_CONST{
    
    
    public static final String TEST_01="TEST";
}

// 在同级别包中进行任意调用不会报错
public class Client {
    
    
    public static void main(String[] args) throws ClassNotFoundException {
    
    
        System.out.println(PACKAGE_CONST.TEST_01);
    }
}

3. Convenient JavaDoc document output

When using JavaDoc, by package-info.javaadding comments, generate JavaDoccomment descriptions to implement the corresponding package.

3.3.Debug to analyze the project

We can analyze the source code function of the project by performing breakpoint debugging on the program project. For example, debug testing can be performed on the most common login part.

According to the breakpoints, you can feel the author's intentions in writing these codes step by step. This is the meaning of open source. It is very important to think and learn from it !

Summarize

So I personally concluded that the process of looking at open source projects at the beginning is not very complicated when there is a foundation, and it is summarized as follows:

1. Learn what is open source
2. Learn to find an open source project that suits the technical architecture you want to see
3. Observe open source projects (see the readme.md document) and download open source projects
4. Analyze the directory structure of the downloaded open source project first, and open the open source project with IDE tools
5. Run open source projects
6. Think about the author's ideas by running the project with a breakpoint (Debug). If you think it is good, you can use it as your own reference code.

---